A command-line tool for Python projects that scans source files for environment variable usage and cross-references them against .env.example to surface missing or undocumented variables before they cause issues in production.
pip install env-grep
Environment variable mismatches are a common source of production failures — a variable used in code but missing from the documented .env.example, or a stale entry in .env.example that no longer maps to anything in the codebase.
env-grep catches both classes of problem locally, before deployment, by statically scanning your Python source files and cross-referencing the results against your .env.example.
# Recommended — installs as a global CLI tool
uv tool install env-grep
# With pip (inside a virtual environment)
pip install env-grepRun from the root of your Python project:
env-grep scan
# or using the short alias
evg scanenv-grep scan [OPTIONS] [PATH]
Arguments:
PATH Directory to scan [default: .]
Options:
-e, --env-file TEXT Path to .env.example [default: .env.example]
-i, --ignore TEXT Name to exclude from scanning (repeatable)
--no-table Output plain text instead of a formatted table
--help Show this message and exit.
env-grep scanning: .
Ignoring: tests
Detected Environment Variables
┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━┓
┃ File ┃ Variable ┃ Line ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━┩
│ app/db.py │ DATABASE_URL │ 12 │
│ app/payments.py │ STRIPE_KEY │ 8 │
└────────────────────┴───────────────┴──────┘
Missing from .env.example:
✗ STRIPE_KEY
No unused variables.
Scan complete — 1 missing, 0 unused.
env-grep scans for the following patterns across all .py files in your project:
Standard os module usage
os.getenv("DATABASE_URL")
os.environ["DATABASE_URL"]
os.environ.get("DATABASE_URL")python-dotenv usage via dotenv_values()
config=dotenv_values(".env")
config["DATABASE_URL"]
config.get("DATABASE_URL")Use --ignore or -i to exclude paths from scanning. The value is matched against each segment of every file path, so it applies at any depth.
# Ignore a directory
env-grep scan --ignore tests
# Ignore a specific file
env-grep scan --ignore legacy.py
# Ignore multiple paths
env-grep scan -i tests -i scripts -i migrationsenv-grep exits with code 1 if any variables are missing from .env.example, making it suitable for use in CI pipelines.
- name: Check environment variablesrun: env-grep scan --no-tableUse --no-table for plain-text output that is easier to read in CI logs.
- Recursively finds all
.pyfiles under the target directory, skipping common non-project paths (.venv,__pycache__,.git,node_modules, etc.) and any user-specified ignores. - Scans each file for environment variable access patterns using regex.
- Parses
.env.exampleto extract all declared variable names. - Computes the difference between variables used in code and variables declared in
.env.example, reporting both missing and unused entries.
env-grep/
├── src/
│ └── env_grep/
│ ├── __init__.py
│ ├── main.py # CLI entrypoint (Typer)
│ ├── scanner.py # Source file scanner
│ └── checker.py # .env.example cross-reference logic
├── tests/
│ ├── test_scanner.py
│ ├── test_checker.py
│ └── test_main.py
├── .github/
│ └── workflows/
│ └── tests.yml
├── pyproject.toml
└── README.md
Issues and pull requests are welcome. If you encounter a pattern that env-grep fails to detect, opening an issue with a minimal example is the most helpful way to report it.
MIT © ratherpixelate