DEV Community

Cover image for I built envcontract: give your .env file a contract (and stop leaking secrets)
Hamza Mansoor
Hamza Mansoor

Posted on

I built envcontract: give your .env file a contract (and stop leaking secrets)

#devops #opensource #tutorial #python

Every project I've worked on relies on a .env file — database URLs, ports, API keys. And every team hits the same three problems with it:

  1. Config drift. A teammate adds a variable and forgets to mention it. Everyone else's app breaks with a cryptic error. "Works on my machine."
  2. Silent misconfiguration. Someone writes PORT=eighty instead of 8080, and it surfaces as a confusing crash hours later.
  3. Leaked secrets. Someone commits a real .env and exposes live credentials on GitHub — one of the most common and costly security mistakes in software.

The .env file runs our apps, but it has no validation, no documentation, and no safety net. So I built a small tool to give it one.

The idea: a contract for your .env

envcontract introduces one committed file — .env.schema — that describes what your configuration should look like: which variables are required, their types, and rules. Crucially, it never contains the secret values themselves. That file is safe to commit and share with your whole team.

version: 1
variables:
  DATABASE_URL:
    type: url
    required: true
    secret: true
  PORT:
    type: int
    default: "3000"
    min: 1
    max: 65535
  STRIPE_KEY:
    type: string
    required: true
    secret: true
    pattern: "^sk_(test|live)_[A-Za-z0-9]+$"
Enter fullscreen mode Exit fullscreen mode

Four commands 

pip install envcontract
Enter fullscreen mode Exit fullscreen mode
  • envcontract init — generates the schema from your existing .env, with every value stripped out and likely secrets auto-flagged.
  • envcontract check — validates any .env against the schema: missing keys, wrong types, failed patterns, out-of-range values. Exits non-zero, so it works in CI.
  • envcontract diff — shows when your local .env has drifted from the team's contract.
  • envcontract guard — a pre-commit hook that blocks you from committing real secret values before they ever reach your repo.

The design choices I care about

100% local. envcontract makes zero network calls and collects zero telemetry. There's an automated test that fails the build if any socket is ever opened. A tool that handles secrets should never send them anywhere — and this one literally can't.

Framework-agnostic. It reads plain .env files, so it works with Python, Node, Go, Ruby, PHP — anything.

Focused. It is not a secrets manager (like Vault or Doppler) and not a generic secret scanner (like gitleaks). It's the small "contract + validation" layer between them.

MIT licensed. Genuinely free — personal or commercial. Fork it, ship it, build on it.

Try it

If .env headaches sound familiar, give it a spin:

pip install envcontract
cd your-project
envcontract init
envcontract check
Enter fullscreen mode Exit fullscreen mode

Code and docs: https://github.com/hamzamansoorch/envcontract
On PyPI: https://pypi.org/project/envcontract/

I'd love feedback — especially on the schema format and whether the guard heuristics match how your team handles secrets. And if it's useful, a star helps others find it.

Top comments (3)

Collapse
 
philmillman profile image
Phil Miller •

We've been thinking about these types of problems for a few years at varlock/dmno. If you'd like to collab on a better python story for varlock, hop in the Discord and give us a shout.

Collapse
 
hamza_mansoor profile image
Hamza Mansoor •

Happy to collab, add me up my username is: hamza_manali

Collapse
 
philmillman profile image
Phil Miller •

I don't think discord will let me add people that I don't share a server with but feel free to drop into the varlock server (link is in the header on varlock.dev) and drop me a line. We just released some Python stuff and I'd love to hear your take varlock.dev/integrations/python/