Django Configurations

2.5.1 · active · verified Tue Apr 14

django-configurations is a helper library for organizing Django project settings by leveraging Python's class inheritance. It extends Django's module-based settings system with object-oriented patterns like mixins and facades, making complex configuration scenarios more manageable, especially for Twelve-Factor app deployments. The current version is 2.5.1, and it maintains an active release cadence with regular updates for new Python and Django versions.

Warnings

breaking The `configurations.Settings` class was removed in version 2.0 in favor of `configurations.Configuration`. Projects upgrading from very old versions must update their base settings class.
Fix: Change `from configurations import Settings` to `from configurations import Configuration` and adjust your settings class inheritance.
breaking Version 2.3 dropped support for Python 2.7 and 3.5, and Django versions older than 2.2. Subsequent major versions have continued to raise the minimum Python and Django requirements.
Fix: Ensure your project runs on Python >=3.8 (currently >=3.9 recommended) and Django >=3.2 (currently >=3.2 required). For example, version 2.4 dropped Python 3.6 and Django < 3.2 support, and version 2.5 dropped Python 3.7 and Django 4.0 support.
gotcha You must use django-configurations's custom `execute_from_command_line` and `get_wsgi_application` functions in your `manage.py`, `wsgi.py`, and `asgi.py` files. Not doing so will prevent your configurations from being loaded correctly.
Fix: Update your `manage.py` to import `execute_from_command_line` from `configurations.management` and your `wsgi.py` (and `asgi.py` if applicable) to import `get_wsgi_application` from `configurations.wsgi` or `configurations.asgi`.
gotcha Django-configurations relies on the `DJANGO_SETTINGS_MODULE` and `DJANGO_CONFIGURATION` environment variables. The `DJANGO_CONFIGURATION` variable specifies which settings class to load from your `DJANGO_SETTINGS_MODULE`.
Fix: Always set `DJANGO_SETTINGS_MODULE` to the path of your settings file (e.g., `mysite.settings`) and `DJANGO_CONFIGURATION` to the name of your desired settings class (e.g., `Dev`, `Prod`). This can be done via shell exports, `.env` files, or directly in your entrypoint scripts (e.g., `manage.py`).
deprecated The utility function `configurations.utils.import_by_path` was deprecated in version 2.3.
Fix: Use `django.utils.module_loading.import_string` instead.

Install

pip install django-configurations Basic installation
pip install 'django-configurations[cache,database,email,search]' Installation with URL-based values support

Imports

Configuration
```
from configurations import Configuration
```
This is the primary base class for defining your Django settings.
values
```
from configurations import values
```
Used for defining settings that can read from environment variables or provide type validation.
execute_from_command_line
```
from configurations.management import execute_from_command_line
```
django-configurations requires its own management command runner to correctly load settings.
get_wsgi_application
```
from configurations.wsgi import get_wsgi_application
```
For WSGI deployments, you must use django-configurations's WSGI application loader.

Quickstart

To use django-configurations, subclass `configurations.Configuration` (or `configurations.Settings` for older versions, though `Configuration` is preferred). Define your settings as class attributes, optionally using `configurations.values` for type-casting environment variables. Modify your `manage.py` and `wsgi.py` files to use `configurations.management.execute_from_command_line` and `configurations.wsgi.get_wsgi_application` respectively. The specific configuration class to load is determined by the `DJANGO_CONFIGURATION` environment variable.

# mysite/settings.py
import os
from configurations import Configuration, values

class Common(Configuration):
    # Build paths inside the project like this: BASE_DIR / 'subdir'.
    BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))

    SECRET_KEY = values.SecretValue()
    DEBUG = values.BooleanValue(False)
    ALLOWED_HOSTS = values.ListValue(['localhost', '127.0.0.1'])

    INSTALLED_APPS = [
        'django.contrib.admin',
        'django.contrib.auth',
        'django.contrib.contenttypes',
        'django.contrib.sessions',
        'django.contrib.messages',
        'django.contrib.staticfiles',
        # Your apps here
    ]

    MIDDLEWARE = [
        'django.middleware.security.SecurityMiddleware',
        'django.contrib.sessions.middleware.SessionMiddleware',
        'django.middleware.common.CommonMiddleware',
        'django.middleware.csrf.CsrfViewMiddleware',
        'django.contrib.auth.middleware.AuthenticationMiddleware',
        'django.contrib.messages.middleware.MessageMiddleware',
        'django.middleware.clickjacking.XFrameOptionsMiddleware',
    ]

    ROOT_URLCONF = 'mysite.urls'

    TEMPLATES = [
        {
            'BACKEND': 'django.template.backends.django.DjangoTemplates',
            'DIRS': [],
            'APP_DIRS': True,
            'OPTIONS': {
                'context_processors': [
                    'django.template.context_processors.debug',
                    'django.template.context_processors.request',
                    'django.contrib.auth.context_processors.auth',
                    'django.contrib.messages.context_processors.messages',
                ],
            },
        },
    ]

    WSGI_APPLICATION = 'mysite.wsgi.application'

    DATABASES = values.DatabaseURLValue('sqlite:///db.sqlite3')

    AUTH_PASSWORD_VALIDATORS = [
        {
            'NAME': 'django.contrib.auth.password_validation.UserAttributeSimilarityValidator',
        },
        {
            'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator',
        },
        {
            'NAME': 'django.contrib.auth.password_validation.CommonPasswordValidator',
        },
        {
            'NAME': 'django.contrib.auth.password_validation.NumericPasswordValidator',
        },
    ]

    LANGUAGE_CODE = 'en-us'
    TIME_ZONE = 'UTC'
    USE_I18N = True
    USE_TZ = True

    STATIC_URL = '/static/'
    DEFAULT_AUTO_FIELD = 'django.db.models.BigAutoField'

class Dev(Common):
    DEBUG = values.BooleanValue(True, environ_name='DJANGO_DEBUG') # Use DJANGO_DEBUG env var, default True


# mysite/manage.py
#!/usr/bin/env python
import os
import sys

if __name__ == "__main__":
    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'mysite.settings')
    os.environ.setdefault('DJANGO_CONFIGURATION', os.environ.get('DJANGO_CONFIGURATION', 'Dev'))

    try:
        from configurations.management import execute_from_command_line
    except ImportError as exc:
        raise ImportError(
            "Couldn't import Django. Are you sure it's installed and "
            "available on your PYTHONPATH environment variable? Did you "
            "forget to activate a virtual environment?"
        ) from exc
    execute_from_command_line(sys.argv)


# mysite/wsgi.py
import os

from configurations.wsgi import get_wsgi_application

os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'mysite.settings')
os.environ.setdefault('DJANGO_CONFIGURATION', os.environ.get('DJANGO_CONFIGURATION', 'Common'))

application = get_wsgi_application()

# For local development, run:
# export DJANGO_CONFIGURATION=Dev
# python manage.py runserver

view raw JSON →