python-decouple

Install the package using pip to start separating your settings from your code.

pip install python-decouple

Environment variables take precedence over both .ini and .env files. You can override a parameter at runtime by prefixing your command with the variable.

DEBUG=True python manage.py

Create a settings.ini file next to your configuration module. Decouple supports string interpolation via ConfigParser. To represent a literal % character, you must escape it as %%.

[settings]
DEBUG=True
TEMPLATE_DEBUG=%(DEBUG)s
SECRET_KEY=ARANDOMSECRETKEY
DATABASE_URL=mysql://myuser:mypassword@myhost/mydatabase
PERCENTILE=90%%
#COMMENTED=42

Create a .env text file in your repository's root directory to store key-value pairs.

DEBUG=True
TEMPLATE_DEBUG=True
SECRET_KEY=ARANDOMSECRETKEY
DATABASE_URL=mysql://myuser:mypassword@myhost/mydatabase
PERCENTILE=90%
#COMMENTED=42

If your environment file is named something other than .env, provide that filename to RepositoryEnv.

import os
from decouple import Config, RepositoryEnv

config = Config(RepositoryEnv("path/to/somefile-like-env"))

To use a .env file located at a specific path, instantiate RepositoryEnv with the desired path and pass it to the Config class.

import os
from decouple import Config, RepositoryEnv

config = Config(RepositoryEnv("path/to/.env"))

Decouple defaults to UTF-8. Since config is lazy, you can change the encoding immediately after import before any configuration is actually accessed.

from decouple import config
import locale

# Set a specific encoding
config.encoding = 'cp1251'
SECRET_KEY = config('SECRET_KEY')

# Or use the system default encoding
config.encoding = locale.getpreferredencoding(False)
SECRET_KEY = config('SECRET_KEY')

To merge multiple environment files, use collections.ChainMap to wrap multiple RepositoryEnv instances. This allows you to layer configuration (e.g., a private file on top of a standard .env file).

from collections import ChainMap
from decouple import Config, RepositoryEnv

config = Config(ChainMap(RepositoryEnv(".private.env"), RepositoryEnv(".env")))

Import the config object to retrieve configuration parameters. You can provide a default value to prevent errors if the key is missing, and a cast argument to convert the string value into a specific Python type (like bool, int, or a custom callable).

from decouple import config

SECRET_KEY = config('SECRET_KEY')  # Raises UndefinedValueError if missing
DEBUG = config('DEBUG', default=False, cast=bool)
EMAIL_HOST = config('EMAIL_HOST', default='localhost')
EMAIL_PORT = config('EMAIL_PORT', default=25, cast=int)

You can dynamically determine the path to your environment file by reading an environment variable (e.g., DOTENV_FILE) using os.environ.get.

import os
from decouple import Config, RepositoryEnv

DOTENV_FILE = os.environ.get("DOTENV_FILE", ".env") # only place using os.environ
config = Config(RepositoryEnv(DOTENV_FILE))