Django Environment Variables: settings.py Patterns

Django has no built-in .env loader — settings.py is plain Python, and the framework expects you to pull configuration from os.environ yourself. That design has not changed from Django 1.0 through Django 6.0 (December 3, 2025), which is why three competing libraries — django-environ, python-dotenv, and python-decouple — all exist to fill the same gap. Get the wiring wrong and the failure modes are not subtle: a string-truthiness bug that leaves DEBUG=True in production, or a rotated SECRET_KEY that silently logs out every user.

How does Django read environment variables?

Through the standard library, like any Python program. settings.py executes once at startup, so anything you read there is fixed for the process lifetime:

# settings.py
import os

# Raises KeyError at startup if missing — good for required values
SECRET_KEY = os.environ["DJANGO_SECRET_KEY"]

# Returns None (or the default) if missing — good for optional values
EMAIL_HOST = os.getenv("EMAIL_HOST", "localhost")

# The classic bug: bool("False") is True. Compare strings explicitly.
DEBUG = os.getenv("DJANGO_DEBUG", "false").lower() in ("true", "1", "yes")

ALLOWED_HOSTS = os.getenv("DJANGO_ALLOWED_HOSTS", "").split(",")

Django itself consumes one environment variable you have already used: DJANGO_SETTINGS_MODULE, which manage.py sets to point at your settings file. Prefer failing loudly — os.environ["KEY"] for anything the app cannot run without — over a default that papers over a missing production value. The Python env variables guide covers os.environ mechanics beyond Django.

django-environ vs python-dotenv vs python-decouple: which should you use?

All three load a .env file; they differ in what happens next.

Opinionated take: for a Django project, pick django-environ — it is the only one that understands Django's config shapes, turning a single DATABASE_URL into the nested DATABASES dict and a REDIS_URL into CACHES. python-dotenv is the better generic tool (and the most actively maintained — its 1.2.2 release fixed CVE-2026-28684, a symlink-following issue in set_key()), but in Django it leaves all casting and URL parsing to you. python-decouple's typed config() API is pleasant and the library is essentially finished software, but it has not shipped a release since 2023 and needs dj-database-url alongside it.

What does a django-environ settings.py look like?

# settings.py
from pathlib import Path
import environ

BASE_DIR = Path(__file__).resolve().parent.parent

env = environ.Env(
    # declare types and defaults in one place
    DEBUG=(bool, False),
    ALLOWED_HOSTS=(list, []),
)

# Read .env in development; harmless no-op if the file is absent
environ.Env.read_env(BASE_DIR / ".env")

SECRET_KEY = env("SECRET_KEY")          # raises ImproperlyConfigured if unset
DEBUG = env("DEBUG")                    # real bool, cast from "true"/"false"
ALLOWED_HOSTS = env("ALLOWED_HOSTS")    # "a.com,b.com" -> ["a.com", "b.com"]

# postgres://user:pass@host:5432/dbname -> full DATABASES["default"] dict
DATABASES = {"default": env.db("DATABASE_URL")}

# redis://host:6379/0 -> CACHES["default"]
CACHES = {"default": env.cache("REDIS_URL", default="locmemcache://")}

# .env — development values, git-ignored
SECRET_KEY=dev-only-key-change-me
DEBUG=true
ALLOWED_HOSTS=localhost,127.0.0.1
DATABASE_URL=postgres://django:django@localhost:5432/myapp

Note the precedence: read_env() does not overwrite variables that already exist in the process environment, so production values injected by your platform always beat the file. If a .env edit seems ignored, that rule — or a wrong working directory — is almost always why; the dotenv-not-loading debugging guide walks the checklist.

How should DEBUG, SECRET_KEY, and ALLOWED_HOSTS be configured?

• DEBUG — default it to False and require an explicit opt-in per environment. Debug pages leak settings, SQL, and stack traces; Django's own deployment checklist (manage.py check --deploy) flags a truthy DEBUG first.
• SECRET_KEY — signs sessions, password-reset tokens, and messages-framework cookies. Generate per environment with get_random_secret_key(), never reuse dev keys in prod, and rotate via SECRET_KEY_FALLBACKS (Django 4.1+): new key in SECRET_KEY, old key appended to the fallbacks list, remove it after sessions age out. Rotating without fallbacks invalidates every session and unexpired password-reset link at once.
• ALLOWED_HOSTS — must be set when DEBUG=False or Django answers every request with a 400. A comma-separated env var split into a list is the standard pattern.

Should production use .env files or real environment variables?

Real environment variables. The .env file is a development convenience; in production it is one more plaintext secrets file to protect, back up, and accidentally bake into a Docker layer. Inject values through the process manager instead:

# /etc/systemd/system/gunicorn.service
[Service]
# Reference a root-owned file outside the project tree…
EnvironmentFile=/etc/myapp/env
ExecStart=/srv/myapp/.venv/bin/gunicorn myapp.wsgi:application

# docker-compose.yml — same idea, container edition
services:
  web:
    image: myapp:latest
    environment:
      DJANGO_DEBUG: "false"
      DATABASE_URL: postgres://django:${POSTGRES_PASSWORD}@db:5432/myapp

Platform dashboards (Heroku, Fly.io, Railway, ECS task definitions, Kubernetes Secrets) all amount to the same thing: the variable exists in the process environment before Python starts, and settings.py reads it with zero file I/O. For the broader rules — naming, startup validation, rotation — see the environment variable best practices guide.

When should you not use environment variables in Django?

• Per-environment Python logic — if staging needs different installed apps or middleware, a settings module per environment (settings/prod.py importing from settings/base.py) is clearer than a thicket of if os.getenv(...) branches. Use env vars for values, settings modules for structure.
• High-value secrets at scale — environment variables are visible in /proc/PID/environ, error-tracker payloads, and child processes. Past a certain blast radius, fetch from a secrets manager at startup instead; the security guide covers when that line is crossed.
• Feature flags that change at runtime — settings.py is evaluated once per process. Anything you want to flip without a restart belongs in the database or a flag service, not the environment.

Frequently Asked Questions

References

• Django docs — Settings — how settings.py is discovered and evaluated
• Django docs — Deployment checklist — DEBUG, SECRET_KEY, ALLOWED_HOSTS, and check --deploy
• Django docs — SECRET_KEY_FALLBACKS — graceful key rotation, added in 4.1
• django-environ — documentation — typed casts, env.db(), env.cache()
• python-dotenv — source on GitHub — the generic .env loader
• python-decouple — source on GitHub — typed config() with .env and settings.ini support