TECHDEV · Open-source tool

env-doctor

Audit your .env files before they bite you. Drift, duplicates, placeholders, risky secrets, dead vars — in one command, with zero dependencies.

View on GitHub →Read docs →

Python · Stdlib only · MIT · No dependencies, no network, no telemetry.

What it checks

Check	What it finds
Drift	Keys in .env.example missing in .env, and vice versa
Duplicates	Same key defined twice
Placeholders	Empty values, changeme, your-api-key, TODO, xxx, …
Risky secrets	Known prefixes (ghp_, sk-, AKIA, …) or long high-entropy values
Unused vars	Keys not referenced in scanned code (--scan .)
Invalid lines	Lines without =, invalid key names

Exit code 0 = no errors, 1 = errors found. Warnings never fail the run on their own.

Install (3 steps)

git clone https://github.com/techdevfun/env-doctor.git
cd env-doctor
# No dependencies to install (Python 3.9+ stdlib only).
# Optional: install the env-doctor command
pip install -e .
# Run it
python -m env_doctor check --env .env --example .env.example

Commands copied exactly from the env-doctor README. Do not use pip install env-doctor — the README does not claim a PyPI install.

Run the check from your PROJECT folder against your project files, not from the env-doctor folder. If you installed with pip install -e ., the command is available from any folder.

Examples

# Clean setup — should pass
python -m env_doctor check --env examples/basic/.env --example examples/basic/.env.example
# Drift + placeholders — should fail with 2 errors
python -m env_doctor check --env examples/drift/.env --example examples/drift/.env.example || true
# JSON output for CI / scripts
python -m env_doctor check --env examples/drift/.env --example examples/drift/.env.example --format json
# Also flag vars not referenced in code
python -m env_doctor check --env .env --example .env.example --scan .

Sample output (from the README drift example)

[ERROR] duplicate-key: Duplicate key 'DATABASE_URL' (line 3)
[ERROR] missing-in-env: 'NEW_API_URL' is in .env.example but missing in .env
[WARN ] placeholder-value: 'STRIPE_KEY' still looks like a placeholder value
[WARN ] missing-in-example: 'OLD_FLAG' is in .env but missing in .env.example
Summary: 2 error(s), 2 warning(s), 3 key(s).

CI

- name: Audit .env drift
  run: python -m env_doctor check --env .env --example .env.example --format text

This repo runs the same check in CI on Python 3.9, 3.11 and 3.12. License: MIT.

Limitations

env-doctor finds risky-looking secrets — it does not fix secrets already leaked. If a real secret was committed, rotate it.
Unused-var detection depends on the code you scan with --scan.
Warnings are heuristics — review them, do not blindly delete vars.

Source + README on GitHub → · Report an issue → · ask@techdev.fun

Have a say

Vote for this tool, suggest a feature, or discuss it with other operators on the community board.