I Built a Django Package That Catches Broken Env Config Before Your Server Starts

Every Django developer has hit this at least once.

You deploy your app, the server starts, and then five minutes later it crashes with a KeyError because someone forgot to add a new environment variable. Or a teammate clones your repo and has no idea what goes in the .env file. Or worse — DEBUG=true silently stays as a string instead of a boolean and nothing works the way it should.

I got tired of debugging these issues and built django-env-doctor to solve them once and for all.

What It Does

django-env-doctor is a Django package that validates, loads, and reports on your environment variables — all from a single schema you define in settings.py.

Instead of scattered os.environ.get() calls across your settings file, you declare all your env variables in one place with their types, rules, and descriptions. The package then:

• Loads your .env file automatically
• Casts values to the correct Python types
• Validates everything against your schema at startup
• Blocks the server from starting if required variables are missing or invalid
• Gives you a clean CLI health report on demand
• Auto-generates a .env.example file from your schema

The Problem With Existing Tools

python-dotenv just loads the file. No validation, no type casting, no schema.

django-environ does type casting but has no structured schema, no CLI report, and fails on the first missing variable instead of reporting all issues at once.

pydantic-settings is powerful but not Django-specific and has no CLI report or .env.example generation.

django-env-doctor fills the gap with zero runtime dependencies.

Installation

pip install django-env-doctor

Add it to your INSTALLED_APPS:

INSTALLED_APPS = [
    ...
    'django_env_doctor',
]

Setup in settings.py

from django_env_doctor import DjangoEnv

env = DjangoEnv(
    schema={
        "SECRET_KEY": {
            "type": "str",
            "required": True,
            "secret": True,
            "min_length": 40,
            "description": "Django secret key",
        },
        "DEBUG": {
            "type": "bool",
            "default": False,
            "description": "Enable debug mode",
        },
        "DATABASE_URL": {
            "type": "url",
            "required": True,
            "description": "Primary database connection URL",
        },
        "ALLOWED_HOSTS": {
            "type": "list",
            "default": [],
            "description": "Comma-separated list of allowed hosts",
        },
        "MAX_UPLOAD_MB": {
            "type": "int",
            "default": 10,
            "min": 1,
            "max": 100,
            "description": "Max file upload size in MB",
        },
    },
    load_file=True,
    env_file=".env",
    raise_on_error=True,
)
SECRET_KEY = env("SECRET_KEY")
DEBUG = env("DEBUG")
ALLOWED_HOSTS = env("ALLOWED_HOSTS")

That is it. One object handles loading, casting, validation, and access.

The CLI Health Report

Run this any time to see the status of your environment:

python manage.py env_doctor

Output:

django-env-doctor
------------------------------------------------------------
[  OK   ]  SECRET_KEY       *** hidden ***
[  OK   ]  DEBUG            → False (default)
[MISSING]  DATABASE_URL     Required variable is not set
[  OK   ]  ALLOWED_HOSTS    → set
[INVALID]  MAX_UPLOAD_MB    Value must be <= 100

------------------------------------------------------------
Total: 5  OK: 3  Missing: 1  Invalid: 1  Warn: 0  Skip: 0
2 issue(s) found. Your app may not start correctly.

No more hunting through logs. One command, full picture.

Generate .env.example Automatically

python manage.py env_doctor --export-example

This generates a .env.example from your schema that stays in sync automatically:

# .env.example
# Auto-generated by django-env-doctor

# Django secret key
# [type=str, required, secret]
SECRET_KEY=your-secret-secret-key

# Enable debug mode
# [type=bool, optional]
DEBUG=False

# Primary database connection URL
# [type=url, required]
DATABASE_URL=

New teammate joins the project? One command and they have everything they need.

Already Using dotenv or django-environ?

No problem. Use django-env-doctor as a validator only on top of your existing loader:

env = DjangoEnv(
    schema={...},
    load_file=False,  # skip loading, just validate
    raise_on_error=True,
)

How to Contribute

The project is open source and contributions are very welcome.

GitHub: https://github.com/wikidjango/django-env-doctor

git clone https://github.com/wikidjango/django-env-doctor
cd django-env-doctor
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest

Things to work on:

• Adding more type validators
• Improving the CLI report formatting
• Adding async support
• Writing more edge case tests
• Improving documentation

Open an issue first if you want to work on something large so we can discuss the approach. For small fixes, pull requests are welcome directly.

Give It a Star

If django-env-doctor saves you from a bad deployment or makes onboarding easier for your team, consider giving it a star on GitHub. It helps other developers find it.

Built with zero runtime dependencies. MIT licensed.