The .env File: A Complete Guide to Environment Variables

What is a .env file? It's a plain-text configuration file that stores environment variables as KEY=value pairs, one per line, loaded into your process at startup so secrets and config never get hardcoded into source. The pattern started as a Ruby gem from Brandon Keepers in 2012, crossed to Node.js the next year via Scott Motte's motdotla/dotenv, and now ships with parsers for every major language. As of Node.js 20.6 (August 2023), you don't even need a library — node --env-file=.env app.js reads the file natively. Bun auto-loads .env with no flag at all; Deno requires both --env-file and --allow-env for sandbox reasons (see the Bun vs Deno vs Node comparison).

How do .env files work?

At process startup, a dotenv parser reads the file line by line and injects each KEY=value pair into the OS environment. In Node.js the values appear on process.env, in Python on os.environ, and so on. The file itself sits next to your code during local development, never gets deployed, and belongs in .gitignore — committing one is the fastest way to leak production credentials.

The pattern descends from the 12-Factor App methodology, published by Heroku co-founder Adam Wiggins in 2011, which says configuration should be strictly separated from code and stored in the environment. There is no formal RFC for the format itself, which is why parser quirks bite in production: a stray space in KEY = value silently breaks the Node.js parser but works fine when sourced from a shell.

What is the .env file syntax?

The .env format is intentionally simple, but there are a few rules worth knowing:

DATABASE_HOST=localhost
PORT=3000

GREETING="Hello, World!"
REGEX='\d+\.\d+'

# Database config
DB_PASSWORD=
DB_NAME=""

PRIVATE_KEY="-----BEGIN RSA KEY-----
MIIBogIBAAJBALRi...
-----END RSA KEY-----"

BASE_URL=https://api.example.com
FULL_URL=${BASE_URL}/v1/users

For an exhaustive parser-by-parser reference — every quoting rule, escape behaviour, and interpolation quirk across Node.js, Python, Ruby, Go, and Docker — see the .env file syntax reference. Here is a complete example:

# App
NODE_ENV=development
PORT=3000

# Database
DATABASE_URL="postgres://user:pass@localhost:5432/mydb"
DATABASE_POOL_SIZE=10

# External APIs
STRIPE_SECRET_KEY=sk_test_abc123
SENDGRID_API_KEY="SG.xxxx"

# Feature flags
ENABLE_CACHE=true

Two of those keys are worth knowing beyond this file: NODE_ENV changes how Express, React, and most build tools behave, and DATABASE_URL has a URI format with its own escaping rules for special characters in passwords.

How do I load .env files in different languages?

Every major language has a dotenv library. Here is how to get started in the most popular ones:

Do you still need the dotenv library in 2026?

Not always. The runtime now loads .env for simple cases, but the library still wins when you need variable interpolation or encrypted, commit-safe secrets. Here is how the four common approaches compare.

Opinionated take: for a fresh Node.js 24 service with no cross-variable references, prefer native --env-file — one fewer dependency and nothing to import. Keep dotenv when a value is built from another, like FULL_URL=${BASE_URL}/v1, which the native loader leaves untouched. Reach for dotenvx when secrets must live safely in git or stay out of an AI agent's reach — its public-key encryption (ECIES, AES-256) keeps the committed file opaque, even though .gitignore never stops a tool from reading the plaintext off disk. For the full Node.js loading story — precedence, process.loadEnvFile(), and CI patterns — see the Node.js environment variables guide.

What are .env file best practices?

1. Never commit .env to git. Add it to your .gitignore immediately. Leaked secrets are the number one cause of security incidents.
2. Provide a .env.example. Commit a template file with dummy values so new team members know which variables are required.
3. Validate at startup. Fail fast if a required variable is missing or malformed. Libraries like envalid (Node.js) or pydantic-settings (Python) make this easy.
4. Use typed configuration objects. Instead of sprinkling process.env.X throughout your codebase, parse variables into a typed config object at the entry point.
5. Separate secrets from config. Non-sensitive values like PORT or LOG_LEVEL can live in .env, but production secrets belong in a secrets manager (Vault, AWS SSM, etc.). For local team workflows, a dev container can mount secrets from the host instead of committing a checked-in .env.
6. Use per-environment files. Many frameworks support .env.development, .env.production, and .env.test to keep environments cleanly separated — Vite's mode system is the canonical example.

What are common .env file pitfalls?

If your variables are unexpectedly undefined at runtime, the most common causes — load order, working directory, production overrides — are walked through in the dotenv not loading debugging guide.

How do you share .env files securely?

Never paste a .env into Slack, email, Discord, or a ticket comment — those channels keep the message indexed forever and sync it to every device the recipient ever signs into. The zero-friction option is send.env.dev: paste the file, get a single-use link, share it, and the link burns on first read. Encryption happens in your browser (the URL fragment carries the key, which browsers never send to servers), hosting is in the EU, and there is no account or CLI to install.

For continuous secret distribution to running apps and CI — not one-off hand-offs — you want a secrets manager instead: 1Password / Bitwarden CLI under 20 people, Doppler or Infisical past that, HashiCorp Vault when compliance demands dynamic credentials. The full sharing guide compares all of them with cost, security, and setup-effort columns.

References

• motdotla/dotenv (Node.js) — the original library that popularised the .env pattern.
• dotenvx — encrypted .env files from the same author, designed to be safe to commit.
• Node.js --env-file CLI reference — the native loader, stable since Node 24.10 / 22.21, including its lack of variable interpolation.
• 12-Factor App: Config — the methodology that says config belongs in the environment, not the codebase.
• Dotenvy file-format reference — the closest thing to a written spec for the dotenv format, including escape and interpolation rules.
• Docker Compose env file documentation — how Compose interpolates and resolves variables from .env.

Where can I learn more about environment variables?