{"id":5764,"library":"django-configurations","title":"Django Configurations","description":"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.","status":"active","version":"2.5.1","language":"en","source_language":"en","source_url":"https://github.com/jazzband/django-configurations","tags":["django","settings","configuration","environment variables","twelve-factor app"],"install":[{"cmd":"pip install django-configurations","lang":"bash","label":"Basic installation"},{"cmd":"pip install 'django-configurations[cache,database,email,search]'","lang":"bash","label":"Installation with URL-based values support"}],"dependencies":[{"reason":"Core dependency for Django projects.","package":"django","optional":false},{"reason":"Optional, for URL-based cache configuration.","package":"django-cache-url","optional":true},{"reason":"Optional, for URL-based database configuration.","package":"dj-database-url","optional":true},{"reason":"Optional, for URL-based email configuration.","package":"dj-email-url","optional":true},{"reason":"Optional, for URL-based search configuration.","package":"dj-search-url","optional":true}],"imports":[{"note":"This is the primary base class for defining your Django settings.","symbol":"Configuration","correct":"from configurations import Configuration"},{"note":"Used for defining settings that can read from environment variables or provide type validation.","symbol":"values","correct":"from configurations import values"},{"note":"django-configurations requires its own management command runner to correctly load settings.","wrong":"from django.core.management import execute_from_command_line","symbol":"execute_from_command_line","correct":"from configurations.management import execute_from_command_line"},{"note":"For WSGI deployments, you must use django-configurations's WSGI application loader.","wrong":"from django.core.wsgi import get_wsgi_application","symbol":"get_wsgi_application","correct":"from configurations.wsgi import get_wsgi_application"}],"quickstart":{"code":"# mysite/settings.py\nimport os\nfrom configurations import Configuration, values\n\nclass Common(Configuration):\n    # Build paths inside the project like this: BASE_DIR / 'subdir'.\n    BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))\n\n    SECRET_KEY = values.SecretValue()\n    DEBUG = values.BooleanValue(False)\n    ALLOWED_HOSTS = values.ListValue(['localhost', '127.0.0.1'])\n\n    INSTALLED_APPS = [\n        'django.contrib.admin',\n        'django.contrib.auth',\n        'django.contrib.contenttypes',\n        'django.contrib.sessions',\n        'django.contrib.messages',\n        'django.contrib.staticfiles',\n        # Your apps here\n    ]\n\n    MIDDLEWARE = [\n        'django.middleware.security.SecurityMiddleware',\n        'django.contrib.sessions.middleware.SessionMiddleware',\n        'django.middleware.common.CommonMiddleware',\n        'django.middleware.csrf.CsrfViewMiddleware',\n        'django.contrib.auth.middleware.AuthenticationMiddleware',\n        'django.contrib.messages.middleware.MessageMiddleware',\n        'django.middleware.clickjacking.XFrameOptionsMiddleware',\n    ]\n\n    ROOT_URLCONF = 'mysite.urls'\n\n    TEMPLATES = [\n        {\n            'BACKEND': 'django.template.backends.django.DjangoTemplates',\n            'DIRS': [],\n            'APP_DIRS': True,\n            'OPTIONS': {\n                'context_processors': [\n                    'django.template.context_processors.debug',\n                    'django.template.context_processors.request',\n                    'django.contrib.auth.context_processors.auth',\n                    'django.contrib.messages.context_processors.messages',\n                ],\n            },\n        },\n    ]\n\n    WSGI_APPLICATION = 'mysite.wsgi.application'\n\n    DATABASES = values.DatabaseURLValue('sqlite:///db.sqlite3')\n\n    AUTH_PASSWORD_VALIDATORS = [\n        {\n            'NAME': 'django.contrib.auth.password_validation.UserAttributeSimilarityValidator',\n        },\n        {\n            'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator',\n        },\n        {\n            'NAME': 'django.contrib.auth.password_validation.CommonPasswordValidator',\n        },\n        {\n            'NAME': 'django.contrib.auth.password_validation.NumericPasswordValidator',\n        },\n    ]\n\n    LANGUAGE_CODE = 'en-us'\n    TIME_ZONE = 'UTC'\n    USE_I18N = True\n    USE_TZ = True\n\n    STATIC_URL = '/static/'\n    DEFAULT_AUTO_FIELD = 'django.db.models.BigAutoField'\n\nclass Dev(Common):\n    DEBUG = values.BooleanValue(True, environ_name='DJANGO_DEBUG') # Use DJANGO_DEBUG env var, default True\n\n\n# mysite/manage.py\n#!/usr/bin/env python\nimport os\nimport sys\n\nif __name__ == \"__main__\":\n    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'mysite.settings')\n    os.environ.setdefault('DJANGO_CONFIGURATION', os.environ.get('DJANGO_CONFIGURATION', 'Dev'))\n\n    try:\n        from configurations.management import execute_from_command_line\n    except ImportError as exc:\n        raise ImportError(\n            \"Couldn't import Django. Are you sure it's installed and \"\n            \"available on your PYTHONPATH environment variable? Did you \"\n            \"forget to activate a virtual environment?\"\n        ) from exc\n    execute_from_command_line(sys.argv)\n\n\n# mysite/wsgi.py\nimport os\n\nfrom configurations.wsgi import get_wsgi_application\n\nos.environ.setdefault('DJANGO_SETTINGS_MODULE', 'mysite.settings')\nos.environ.setdefault('DJANGO_CONFIGURATION', os.environ.get('DJANGO_CONFIGURATION', 'Common'))\n\napplication = get_wsgi_application()\n\n# For local development, run:\n# export DJANGO_CONFIGURATION=Dev\n# python manage.py runserver","lang":"python","description":"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."},"warnings":[{"fix":"Change `from configurations import Settings` to `from configurations import Configuration` and adjust your settings class inheritance.","message":"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.","severity":"breaking","affected_versions":">=2.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.3"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`).","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use `django.utils.module_loading.import_string` instead.","message":"The utility function `configurations.utils.import_by_path` was deprecated in version 2.3.","severity":"deprecated","affected_versions":">=2.3"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}