envsleuth

🌐 English · 简体中文 · Русский

envsleuth parses Python source code with AST, finds reads through os.getenv(), os.environ[], and os.environ.get(), then reports variables that are missing from .env.

Install

pip install envsleuth

Usage

# scan current directory, check against ./.env
envsleuth scan

# specific directory, specific env file
envsleuth scan --path ./src --env .env.production

# CI mode — exits 1 if anything is missing
envsleuth scan --strict

# generate a .env.example from your code
envsleuth generate

# machine-readable output
envsleuth scan --json

Example output

Found 6 variables in code
checking against .env

⚠️  AWS_SECRET — not in .env but has default in code (probably ok)
✅ DATABASE_URL
✅ DEBUG
❌ REDIS_URL — missing from .env
     at src/app.py:7
✅ SECRET_KEY
❌ STRIPE_API_KEY — missing from .env
     at src/app.py:6

⚠️  1 dynamic usage (variable name computed at runtime, can't check statically)
     src/app.py:12  →  getenv(name)

ℹ  1 variable in .env not referenced in code: UNUSED_VAR

3 ok  1 with default  2 missing

What it detects

Works with all three common patterns:

import os

a = os.getenv("A")              # required — must be in .env
b = os.getenv("B", "fallback")  # has default — warned but not required
c = os.environ["C"]             # required (would raise KeyError without)
d = os.environ.get("D")         # required

Also handles aliased imports:

from os import getenv, environ
import os as sys_os

a = getenv("A")
b = environ["B"]
c = sys_os.getenv("C")

Variables with names computed at runtime (e.g. os.getenv(f"PREFIX_{x}")) can't be checked statically — they're reported in a separate warning section so you know they exist.

Django and config libraries

envsleuth also understands the two most common third-party config patterns:

# django-environ
import environ
env = environ.Env()
SECRET_KEY = env('SECRET_KEY')
DEBUG = env.bool('DEBUG', default=False)
DATABASES = {'default': env.db('DATABASE_URL')}
ALLOWED_HOSTS = env.list('ALLOWED_HOSTS', default=[])

# python-decouple
from decouple import config
SECRET_KEY = config('SECRET_KEY')
DEBUG = config('DEBUG', default=False, cast=bool)

Calls through env(...), env.get_value(...), and the typed helpers are detected: str, bytes, bool, int, float, json, list, tuple, dict, url, db_url/db, cache_url/cache, email_url/email, search_url, channels_url/channels, and path. FileAwareEnv and Env.configured(...) are supported too, including defaults declared in their schemas and statically known env.prefix settings. Aliased imports work as well: from decouple import config as cfg.

CI: GitHub Actions annotations

Get missing env vars surfaced as PR annotations on the exact source lines:

# .github/workflows/env-check.yml
- name: Check env vars
  run: envsleuth scan --output github --strict

Each missing var becomes an ::error annotation; dynamic lookups become ::warning. The format follows GitHub's workflow command spec.

pre-commit hook

Add envsleuth to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/k38f/envsleuth
    rev: v0.3.0
    hooks:
      - id: envsleuth
        # optional overrides
        # args: [--path, src, --env, .env]

Runs envsleuth scan --strict when Python, .env, .env.*, or .envignore files change. There's also an opt-in envsleuth-generate hook for regenerating .env.example manually via pre-commit run envsleuth-generate --hook-stage manual.

envsleuth generate

Scans your code and writes a .env.example with every variable found, a comment pointing at where it's used, and the default value from code if there is one:

$ envsleuth generate
Wrote 6 variables to .env.example

$ cat .env.example
# Generated by envsleuth — edit this file before committing.
# Each variable below is used somewhere in your code.

# used at src/app.py:8
AWS_SECRET=default-value

# used at src/app.py:3
DATABASE_URL=

# used at src/app.py:5
DEBUG=false
...

Use --force to overwrite an existing file, --output path/to/file to write elsewhere.

Generation is fail-closed: if a source file cannot be scanned or a variable name cannot be written as a portable environment assignment, the command exits with code 2 without creating or overwriting the target, even with --force. Dynamic lookups are preserved as warning comments. Literal defaults are written only when they can be represented consistently for both python-dotenv and a POSIX shell; otherwise the value is left blank with a # default omitted note. On Windows, generation also rejects names that differ only by case (for example, FOO and foo) because the Windows environment cannot keep them separate.

.envignore

Exclude variables from the "missing" check with glob patterns — one per line:

# .envignore
TEST_*
LEGACY_*
DEBUG_TOOL

Great for vars that come from CI, Docker, or your shell rc files rather than the local .env.

CLI reference

envsleuth scan

envsleuth generate

Exit codes

• 0 — the command completed successfully.
• 1 — scan --strict found required variables missing from an existing .env.
• 2 — an operational failure, such as a missing .env, an incomplete scan, an invalid path, or a read/write/generation error. JSON and GitHub output still emit a structured error report first when possible.

Update notifications

envsleuth checks PyPI for new releases at most once per week. When a new version is available, it prints a single line to stderr:

ℹ  envsleuth 0.3.0 is available (you have 0.2.0). Run: pip install -U envsleuth

The check is cached, runs with a short timeout, and stays silent on any error (offline, blocked network, etc). To disable it entirely:

# per-command
envsleuth scan --no-update-check

# globally for your shell
export ENVSLEUTH_NO_UPDATE_CHECK=1

The cache lives at ~/.cache/envsleuth/last_check.json (or $XDG_CACHE_HOME/envsleuth/...).

How it compares

These tools solve different problems: envsleuth scans source code, dotenv-linter inspects .env files, and python-decouple reads configuration at runtime.

Dependencies

• click — CLI
• python-dotenv — .env parsing
• flashbar — progress bar used when scanning 20+ files
• packaging — PEP 440 version comparison for update checks

The scanner itself uses only the Python standard library (ast).

License

MIT