What a .env file looks like
# App NODE_ENV=development PORT=3000 # Database DATABASE_URL=postgres://app:secret@localhost:5432/app # Secrets JWT_SECRET=3f9a8c1e… # generate, never type SMTP_PASSWORD="pa ss#word" # quotes: spaces and # inside the value
- Keys are case-sensitive and by convention
UPPER_SNAKE_CASE; letters, digits and_, not starting with a digit. - Values are always strings.
PORT=3000gives"3000"; converting to numbers or booleans is your code's job. - Comments start with
#. Inline comments need a space before#, and some loaders cut unquoted values at any#, so quote values that contain one. - Quotes are optional but needed for spaces,
#and line-break escapes (\nworks inside double quotes).
Check a file against these rules with the .env validator, or start from a ready template in the .env generator.
Why .env files exist
The Twelve-Factor App methodology (factor III, "Config") says configuration that changes between deploys belongs in the environment, not in code. Real environment variables are tedious to set by hand on a laptop, so tools like dotenv read them from a file instead. Your code only ever reads process.env.DATABASE_URL; whether the value came from a file locally or from the host's settings in production doesn't matter to it.
How each stack loads a .env file
| Stack | How it loads | Read a value |
|---|---|---|
| Node.js 20.6+ | node --env-file=.env app.js or import "dotenv/config" | process.env.KEY |
| Next.js | automatic: .env, .env.local, .env.[mode], .env.[mode].local | process.env.KEY; client only NEXT_PUBLIC_* |
| Vite / React | automatic, client only VITE_* | import.meta.env.VITE_KEY |
| Python | from dotenv import load_dotenv; load_dotenv() | os.environ["KEY"] |
| Django | django-environ: environ.Env.read_env() | env("KEY") |
| Rails | dotenv-rails gem (development/test) | ENV["KEY"], ENV.fetch("KEY") |
| Laravel | built in (vlucas/phpdotenv) | env("KEY") in config files only |
| Go | godotenv.Load() | os.Getenv("KEY") |
| Docker | docker run --env-file .env, Compose env_file: | inside the container's environment |
Next.js decides between files by priority, highest first: .env.[mode].local, .env.local, .env.[mode], .env. A variable already set in the environment beats all of them. Step-by-step setup for each framework: how to use dotenv.
.env vs .env.local vs .env.example vs .env.production
| File | Purpose | Commit to git? |
|---|---|---|
.env | default values; in many projects also local secrets | only if it holds no secrets |
.env.local | your machine's overrides and secrets (Next.js, Vite) | never |
.env.example | every key, no secret values: the template | always |
.env.development / .env.production | non-secret defaults per mode (Next.js, Vite) | yes, if no secrets |
.env.test | values for the test runner | if no secrets |
Create the template from a working file with the .env.example generator, and keep the real files out of git: how to hide .env from git.
.env vs JSON, YAML and Docker config
| Format | Nesting | Loader support | Best for |
|---|---|---|---|
| .env | flat only | universal: dotenv in every language, Docker, every PaaS | secrets, per-environment values |
| config.json | nested | custom code | structured, non-secret app config |
| config.yaml | nested, comments | YAML library | human-edited config, Kubernetes |
Compose environment: | flat | Docker Compose | container overrides |
Many apps use both: a JSON/YAML file for structure, .env for secrets and environment-specific values. Converters: ENV to JSON, ENV to YAML; full comparison: .env vs JSON config.
Why .env files break production
- Missing key:
process.env.API_KEYisundefined, and the crash happens later, far from the cause. Validate required keys at startup. - Not deployed: the host never sees your file; every key must be set in its settings.
- Duplicate key: the last definition silently wins.
- Unquoted `#` or `$`: values get cut or expanded.
- Committed secret: once in git history, it must be rotated.
Symptoms and fixes for each: how to fix .env errors. The rules that prevent them: .env best practices.
Frequently asked questions
What is a .env file?
A plain-text file, usually in the project root, that stores configuration as KEY=value lines. Apps load it into environment variables at startup to keep settings and secrets out of the source code.
What does env stand for?
Environment, as in environment variables: named values the operating system or runtime gives a process. A .env file is a convenient way to set many of them at once during development.
Is it safe to commit a .env file to git?
Not if it contains secrets. Commit .env.example instead and add .env* to .gitignore. A secret that was ever committed must be rotated; deleting the file doesn't remove it from history.
How do I open or create a .env file?
It's a normal text file whose name starts with a dot. Create it in any code editor; on macOS and Linux it's hidden in file browsers (Cmd+Shift+. shows it in Finder), and on Windows make sure the editor doesn't save it as .env.txt.
What happens if a required variable is missing?
Usually nothing at first: Node returns undefined, Python's os.getenv returns None. The failure shows up later, e.g. as a database connection error. Validate required variables at startup so the app refuses to start instead.