django-envconfig

django-envconfig

Configure Django using environment variables (envvars). settings.py optional.

Getting started

Installation

python -m pip install django-envconfig

Usage

Edit the manage.py, asgi.py and wsgi.py files generated by Django's startproject command and modify the following line:

os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'envconfig.settings')

Minimum configuration

The following envvars are required (if settings.py is removed):

• ALLOWED_HOSTS (unless you set DEBUG=on)

Environments may be stored in an .env file. This file can be stored in your root directory (next to manage.py) or anywhere on the path (e.g. virtualenv directory).

How it works

Any Django setting can be configured as an environment variable.

• To set booleans: true|yes|on|1 and false|no|off|0 (case-insensitive)
• To set None: none|null (case-insensitive)
• Simple lists of strings can be stored comma-separated e.g. export ALLOWED_HOSTS=127.0.0.1,localhost
• Dicts and complex lists should be stored as JSON

Settings are loaded with the following priority (highest first):

1. Environment variables.
2. Settings defined in your projects settings.py, if it exists. Note: any custom settings should be defined here with their default value.
3. Settings that would be defined by a settings.py file generated by startproject. This should eliminate the need for the file in (2) for most projects. Caveats:
   • The default value for DEBUG has been changed to False.
   • A SECRET_KEY is generated but will not persist between sessions (e.g. if you restart your server/process manager). Check the Django documentation to see whether you need to set a persistent SECRET_KEY as an environment variable.

django-envconfig environment variables

Helper environment variables to use with django-envconfig:

Environment variable	Description
DJANGO_PROJECT	May be required if django-envconfig cannot find your project. Set to the name of the module originally generated by startproject
ADD_INSTALLED_APPS	Add to INSTALLED_APPS
REMOVE_INSTALLED_APPS	Remove from INSTALLED_APPS
ADD_MIDDLEWARE	Add to MIDDLEWARE
REMOVE_MIDDLEWARE	Remove from MIDDLEWARE

PostgreSQL environment variables

If you are using a PostgreSQL backend you do not need to set DATABASES. You can simply set PostgreSQL environment variables - the minimum is PGDATABASE. See the PostgreSQL docs for the full list of envvars. This way the same environment can be used when calling PostgreSQL command line utilities such as psql or pg_dump.

Why

• To separate configuration from code. See The Twelve Factor App.
• Use serverless services such as AWS Lambda and Heroku.
• Avoid having to template settings files and keep the auto-generated settings.py up to date between Django versions.
• Use .env files for easy switching between environments/deployments (e.g. dev, test and prod).

Dependencies

• python-dotenv (BSD 3-clause license)

License

MIT.