Install & Compatibility
Where this runs
tested against v5.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.922s · 66.9MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.5s · import 0.816s · 67MB
66MB installed
● package 66MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
flag_enabled
✓ from flags.state import flag_enabled
Used to check the state of a flag in Python code (e.g., in views or management commands).
feature_flags (template tag)
✓ {% load feature_flags %}
Required to use flag checking in Django templates via `{% flag_enabled 'MY_FLAG' as my_flag %}`.
flagged_path
✓ from flags.urls import flagged_path
Used in `urlpatterns` to conditionally include URL patterns based on a flag's state.
flag_required
✓ from flags.decorators import flag_required
Decorator to protect an entire view based on a feature flag's state.
conditions (module)
✓ from flags import conditions
Used for registering custom flag conditions.
FlaggedViewMixin, FlaggedTemplateView
✓ from flags.views import FlaggedViewMixin, FlaggedTemplateView
Mixins and views for integrating flags into class-based views.
To get started, add 'flags' to your `INSTALLED_APPS` and ensure `django.template.context_processors.request` is in your `TEMPLATES` context processors for request-aware conditions. Define your flags and their conditions in `settings.py` within the `FLAGS` dictionary. Then, use `flag_enabled` in your Python code, `{% load feature_flags %}` in templates, or `flagged_path` in `urls.py` to gate functionality. Finally, run `python manage.py migrate`.
import os
# settings.py
INSTALLED_APPS = [
# ...
'flags',
# ...
]
TEMPLATES = [
{
'BACKEND': 'django.template.backends.django.DjangoTemplates',
'OPTIONS': {
'context_processors': [
# ...
'django.template.context_processors.request',
# ...
],
},
},
]
FLAGS = {
'MY_NEW_FEATURE': [
{'condition': 'boolean', 'value': os.environ.get('ENABLE_MY_NEW_FEATURE', 'False').lower() == 'true'}
],
'BETA_ACCESS': [
{'condition': 'user', 'value': 'admin'},
{'condition': 'parameter', 'value': 'beta', 'required': False} # Can be overridden by URL param `?beta=true`
]
}
# views.py
from django.http import HttpResponse
from flags.state import flag_enabled
def my_feature_view(request):
if flag_enabled('MY_NEW_FEATURE', request=request):
return HttpResponse("Welcome to the new feature!")
return HttpResponse("Feature coming soon.")
# urls.py
from django.urls import path
from flags.urls import flagged_path
from . import views
urlpatterns = [
path('home/', views.my_feature_view, name='home'),
flagged_path('BETA_ACCESS', 'beta-page/', views.my_beta_view, name='beta_page')
]
# After adding to INSTALLED_APPS and settings, run migrations:
# python manage.py migrate
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'flags'
The 'flags' app is not registered in Django's INSTALLED_APPS.
fixAdd `'flags'` to your `INSTALLED_APPS` list in `settings.py`.
TypeError: 'dict' object is not iterable
In `settings.FLAGS`, a flag's conditions are defined as a single dictionary instead of a list containing dictionaries, which was removed in Django-Flags 5.0.
fixChange the flag definition in `settings.py` from `{'FLAG_NAME': {'condition': '...', 'value': ...}}` to `{'FLAG_NAME': [{'condition': '...', 'value': ...}]}` (a list of dictionaries). django.core.exceptions.ImproperlyConfigured: The 'request' context processor is required
The `django.template.context_processors.request` is missing from your `TEMPLATES` context processors, which is necessary for many flag conditions and template tags.
fixAdd `'django.template.context_processors.request'` to the `'context_processors'` list within your `TEMPLATES` configuration in `settings.py`.
404 Not Found (for a URL managed by flagged_path)
A `flagged_path` URL pattern was accessed, but the associated flag's conditions were not met and no `fallback` view was specified to handle this state.
fixEither ensure the flag conditions are met, or provide a `fallback` view to `flagged_path` (e.g., `flagged_path('MY_FLAG', 'my-url/', my_view, fallback=fallback_view)`). Upgrade
Version history
5.2.0latest on PyPI · released Feb 10, 2026
Audit
Dependencies
DjangorequiredCore framework dependency; supports Django 4.x, 5.x, 6.0 in recent versions.
PythonrequiredRequires Python >=3.10 as of version 5.1.0.