dotenv-lint 1.0.0

Validate .env files against a schema with secret strength checking

envguard

Validate .env files against a schema, with secret-strength heuristics, drift detection between environments, and a CI-friendly CLI. Zero runtime dependencies — pure Python 3.8+.

Install

pip install dotenv-lint
# dev tools
pip install -e .[dev]

The PyPI distribution is named dotenv-lint because envguard and similar variants were taken / blocked by PyPI's name-similarity filter. The import name (envguard) and CLI command (envguard) are unchanged.

Quick start

Declare a schema in .env.schema.toml:

[DATABASE_URL]
type     = "url"
required = true

[PORT]
type     = "int"
required = true
range    = [1024, 65535]

[JWT_SECRET]
type        = "str"
required    = true
secret      = true
min_length  = 32

Validate from the CLI:

envguard validate .env --schema .env.schema.toml
envguard validate .env --schema .env.schema.toml --format json
envguard validate .env --schema .env.schema.toml --strict --exit-on-fail
envguard secrets .env
envguard compare .env.development .env.production
envguard scaffold .env > .env.schema.toml

Or from Python:

from envguard import validate

result = validate(env_file=".env", schema=".env.schema.toml")
if not result.is_valid:
    for err in result.errors:
        print(err.code, err.message)
    raise SystemExit(1)

Exit codes

Code	Meaning
0	All checks passed
1	One or more errors found
2	One or more warnings (no errors)
3	File not found or unreadable

Schema format

TOML is the primary format (.env.schema.toml); JSON is also accepted (.env.schema.json). The built-in TOML reader is a constrained subset sufficient for the schema layout — top-level tables containing scalars, booleans, and single-line arrays. If you need richer TOML syntax, switch to JSON.

Supported types: str, int, float, bool, url, email, list, json, path, uuid. Constraints per key: required, default, description, secret, choices, range, schemes (URLs), min_length, max_length, must_exist (paths).

Secret strength

When secret = true, EnvGuard runs five heuristics: minimum-length, Shannon-entropy, blocklist, sequential/repeated/keyboard-walk patterns, and all-same-case. Findings come back as WEAK_SECRET / PLAINTEXT_SECRET_PATTERN warnings with HIGH/MEDIUM/LOW severity.

Pre-commit hook

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/FaraiMacheka/envguard
    rev: v1.0.0
    hooks:
      - id: envguard
        args: [".env", "--schema", ".env.schema.toml", "--exit-on-fail"]

The hook calls envguard validate with the args you supply, so point it at whichever .env and schema your repo uses.

Security

For vulnerability reports, see SECURITY.md.

License

MIT.