guide8 min readBy Aliniyaz Mamat · updated

What is a .env file? A developer's guide (2026)

A .env file is a plain-text file in your project root that stores configuration as KEY=value lines, such as database URLs, API keys and feature flags. Your app loads it into environment variables at startup, so the same code runs in development, staging and production with different settings and no secrets in the source code.

Key takeaways

  • ✓Format: one KEY=value per line, # for comments, quotes for values with spaces or #. Every value is a string.
  • ✓"env" stands for environment: the file fills the same environment variables your OS or host would set (process.env, os.environ, ENV).
  • ✓It's for local development. In production, the host (Vercel, Docker, Kubernetes) sets the variables and no .env file is deployed.
  • ✓Never commit .env; commit .env.example with the keys and no secret values.
  • ✓If a key appears twice, the last definition wins; a real environment variable beats the file.

What a .env file looks like

.env
# 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=3000 gives "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 (\n works 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

StackHow it loadsRead a value
Node.js 20.6+node --env-file=.env app.js or import "dotenv/config"process.env.KEY
Next.jsautomatic: .env, .env.local, .env.[mode], .env.[mode].localprocess.env.KEY; client only NEXT_PUBLIC_*
Vite / Reactautomatic, client only VITE_*import.meta.env.VITE_KEY
Pythonfrom dotenv import load_dotenv; load_dotenv()os.environ["KEY"]
Djangodjango-environ: environ.Env.read_env()env("KEY")
Railsdotenv-rails gem (development/test)ENV["KEY"], ENV.fetch("KEY")
Laravelbuilt in (vlucas/phpdotenv)env("KEY") in config files only
Gogodotenv.Load()os.Getenv("KEY")
Dockerdocker 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

FilePurposeCommit to git?
.envdefault values; in many projects also local secretsonly if it holds no secrets
.env.localyour machine's overrides and secrets (Next.js, Vite)never
.env.exampleevery key, no secret values: the templatealways
.env.development / .env.productionnon-secret defaults per mode (Next.js, Vite)yes, if no secrets
.env.testvalues for the test runnerif 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

FormatNestingLoader supportBest for
.envflat onlyuniversal: dotenv in every language, Docker, every PaaSsecrets, per-environment values
config.jsonnestedcustom codestructured, non-secret app config
config.yamlnested, commentsYAML libraryhuman-edited config, Kubernetes
Compose environment:flatDocker Composecontainer 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_KEY is undefined, 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.

Related tools

Continue reading