A .env style guide that works in every language
Dotenv parsers in Node.js, Python, Ruby, Go and PHP agree on a small common core. Stick to it and the same file works everywhere:
- Key names:
UPPER_SNAKE_CASE, letters, digits and underscores, not starting with a digit. - No spaces around `=` in files used by Docker or shell scripts;
KEY=value, notKEY = value. - Quote values that contain spaces,
#or line-break escapes. Use single quotes when a$must stay literal (dotenv-expand and Compose do not expand inside single quotes). - One key per line, comments on their own line above the key.
- Group by service with a comment heading, and keep the same order in
.env.example.
# ── Database ────────────────────── DATABASE_URL=postgres://app:app@localhost:5432/app DATABASE_POOL_SIZE=10 # ── Stripe ──────────────────────── # Dashboard > Developers > API keys (test mode) STRIPE_SECRET_KEY=sk_test_xxx STRIPE_WEBHOOK_SECRET=whsec_xxx # ── App ─────────────────────────── APP_NAME="Acme Billing" LOG_LEVEL=info
What each option does
| Option | Effect | Changes what the app reads? |
|---|---|---|
| sort | keys A→Z, comments move with their key | no |
| align = | pads key names so = lines up | no for dotenv; yes for docker --env-file |
| dedupe | keeps the last definition of each key | no (dotenv already uses the last one) |
| group by prefix | groups by the part before the first _, adds # PREFIX headings | no |
| UPPER | uppercases key names | yes, only use it if your code reads uppercase names |
For pure cleanup without reordering, use the ENV cleaner. To compare the formatted file with another environment, paste both into the ENV diff checker.
Enforcing the format in CI
The open-source dotenv-linter (written in Rust) checks key order, duplicates, spacing and quotes in a pipeline. A minimal GitHub Actions step:
- name: Lint .env.example
run: |
curl -sSfL https://raw.githubusercontent.com/dotenv-linter/dotenv-linter/master/install.sh | sh -s
./bin/dotenv-linter .env.exampleLint the committed .env.example, not the real .env, which should never be in the repository. See the guide .env best practices for the rest of the conventions.