The Complete .env File Syntax Reference

The .env file format has no formal specification. The env file syntax that ships in motdotla/dotenv 17.x for Node.js diverges from theskumar/python-dotenv 1.0, Ruby bkeepers/dotenv 3.2, joho/godotenv 1.5, and the parser inside Docker Compose v2 in small ways that look like bugs but leak passwords or truncate URLs in practice. motdotla/dotenv v15.0.0 (Jan 31, 2022) made # the inline-comment marker on unquoted values by default — the upgrade caught teams pinned to v14 with a # in a password.

This reference documents the real .env file format rules — quoting, comments, multi-line values, variable expansion, and the export prefix — with explicit notes on where each implementation diverges. Use the env validator to check your files against these rules instantly.

What is the basic KEY=VALUE syntax?

Every .env file is a plain-text file where each line defines one environment variable as a KEY=VALUE pair. Keys are uppercase by convention and may contain letters, digits, and underscores. The value starts immediately after the first = character.

DATABASE_HOST=localhost
PORT=3000
API_KEY=sk_live_abc123

Blank lines are ignored. A line that contains only whitespace is also ignored.

How do quoting rules work?

Values can be unquoted, single-quoted, or double-quoted. The quoting style determines how the parser handles special characters, whitespace, and escape sequences.

APP_NAME=my-app
DEBUG=true

GREETING="Hello, World!"
MESSAGE="Line one\nLine two"
PASSWORD="p@ss#word with spaces"

REGEX='\d+\.\d+'
TEMPLATE='Hello $USER, welcome!'
RAW_PATH='C:\Users\admin'

How do I add comments to a .env file?

Put a # at the start of a line — every major parser (Node.js motdotla/dotenv 17.x, python-dotenv 1.0, Ruby bkeepers/dotenv 3.2, Go joho/godotenv 1.5, Docker Compose v2) ignores the line. Leading whitespace before the # is fine. Blank lines are also ignored.

# Database configuration
DB_HOST=localhost

  # Indented comments are also valid
DB_PORT=5432

The trickier question is inline comments — does KEY=value # comment set the value to value or to value # comment? Behavior diverges by library and version, and the divergence has shipped real bugs.

// .env
TOKEN=abc#123 # API token
QUOTED_TOKEN="abc#123" # API token

// Node.js with dotenv@17 (or @15+)
require('dotenv').config();
process.env.TOKEN;        // "abc"
process.env.QUOTED_TOKEN; // "abc#123"

# .env
TOKEN=abc#123 # API token
NO_SPACE=abc#123# API token
QUOTED_TOKEN="abc#123" # API token

# Python with python-dotenv@1.0
from dotenv import dotenv_values
dotenv_values('.env')
# {'TOKEN': 'abc#123', 'NO_SPACE': 'abc#123# API token',
#  'QUOTED_TOKEN': 'abc#123'}

# .env consumed by env_file in docker-compose.yml
TOKEN=abc#123 # API token       # → TOKEN=abc#123
NO_SPACE=abc#123# API token     # → NO_SPACE=abc#123# API token
QUOTED_TOKEN="abc#123" # token  # → QUOTED_TOKEN=abc#123

The portable rule: never rely on inline comments for any value containing #, and quote the value whenever it might. URLs with fragment identifiers are the most common landmine — see the dotenv-not-loading guide for the full failure-mode list.

# Dangerous — may be truncated to "https://example.com/path"
URL=https://example.com/path#anchor

# Safe — quotes preserve the full value
URL="https://example.com/path#anchor"

How do I write multi-line values in a .env file?

Two approaches. The first works in every parser; the second is parser- and version-dependent. The most common real-world need is shipping an RSA or EC private key (TLS certificates, JWT signing, GitHub App credentials) without flattening it onto one line.

MULTILINE="line one\nline two\nline three"

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

If you have to support Docker Compose and a Node.js or Python service from the same .env file, use the \n-escape form — it survives every parser. For storage and rotation considerations of multi-line secrets, see .env vars security best practices.

How does variable expansion work?

Variable interpolation lets you reference other variables defined earlier in the same file or already present in the environment. Both $VAR and ${VAR} syntax are supported.

BASE_URL=https://api.example.com
# Both forms reference BASE_URL
API_V1=$BASE_URL/v1
API_V2=${BASE_URL}/v2

Variable expansion is disabled inside single quotes. This is consistent across all major implementations. It is enabled in double quotes and unquoted values in Node.js dotenv (with dotenv-expand), Python python-dotenv, and Go godotenv. Ruby dotenv enables it by default in all quoting styles except single quotes.

What about empty and missing values?

There is an important distinction between an empty value and an absent variable.

# Empty string — the variable exists but has no content
DB_PASSWORD=
DB_NAME=""
DB_HOST=''

# These three all set the variable to an empty string ""

If a key is not present in the .env file at all, most dotenv libraries will not set it, and the variable will be undefined (Node.js) or None (Python) unless it was already defined in the system environment.

How are spaces and the = sign handled?

The treatment of whitespace around the = sign differs between implementations. Most dotenv libraries do not allow spaces around the equals sign.

# Correct — no spaces around =
DATABASE_URL=postgres://localhost/mydb

# Risky — spaces around = may cause parse errors or unexpected keys
DATABASE_URL = postgres://localhost/mydb

For unquoted values, most parsers trim trailing whitespace. Leading whitespace after = is also typically trimmed. However, inside quotes, all whitespace is preserved exactly as written. The safest practice is to never rely on trimming — quote values that contain meaningful whitespace.

How do implementations differ across languages?

Because there is no formal specification, each dotenv library makes its own parsing decisions. The following table summarizes the key differences.

What does the export prefix do?

Some .env files use export KEY=VALUE so the file can be sourced directly in a shell session. Most dotenv parsers silently strip the export prefix and treat the line normally. Docker Compose is the notable exception — it does not recognize the prefix and will either error or treat the entire string as the key.

# Works in shell (source .env) and most dotenv parsers
export DATABASE_URL=postgres://localhost/mydb
export NODE_ENV=production

# Docker Compose: remove the export prefix
DATABASE_URL=postgres://localhost/mydb

What are the most common gotchas?

What does a complete .env file look like?

This example demonstrates every syntax feature described above in a single file.

# Basic key-value pairs
NODE_ENV=development
PORT=3000

# Double-quoted value with spaces and escape sequences
GREETING="Hello, World!"
MULTILINE="first line\nsecond line"

# Single-quoted literal value — no interpolation
REGEX='\d{3}-\d{4}'

# Variable expansion (requires dotenv-expand in Node.js)
BASE_URL=https://api.example.com
FULL_URL=${BASE_URL}/v2/users

# Empty values
OPTIONAL_FLAG=
ALSO_EMPTY=""

# Export prefix (stripped by most parsers, not Docker Compose)
export LOG_LEVEL=debug

# Multiline value with real newlines
PRIVATE_KEY="-----BEGIN EC KEY-----
MHQCAQEEIBkg...
-----END EC KEY-----"

References

• motdotla/dotenv — parsing rules — the canonical Node.js dotenv parser and its rule list.
• python-dotenv — file format — Python's reference dotenv implementation, covering quoting and multiline support.
• godotenv — examples — Go port of the Ruby dotenv with comments-and-exports support.
• Docker Compose — .env file syntax — official reference for the Compose-specific parser, including the `:` delimiter and inline-comment rules.
• dotenvy — dotenv file format — Elixir's deliberate divergence from the original spec, useful as a contrast.

Related on env.dev

• The complete .env guide — setup, best practices, and language examples.
• Why is my .env file not loading? — most failures trace back to the syntax rules above.
• Sharing .env files securely — once the syntax is right, share the file without leaking secrets.
• Validate your .env file online — checks values against these parsing rules instantly.