.env File Syntax Explained: The Complete Dotenv Format Guide

.env has no official specification. It started as a convention in Ruby's dotenv gem, got copied into Node's dotenvpackage, then into Docker Compose, then into a dozen language-specific loaders — and each one implemented its own parser, with its own opinion on quoting, comments, and multi-line values. Most of the time the differences don't matter, because most .env files only ever contain KEY=value pairs with no punctuation worth disagreeing about. They matter the moment a value contains a #, a space, a newline, or a $— and that's exactly when a file that looks fine gets parsed differently by two tools reading the same line.

The rules below are the common ground across the major loaders (Node's dotenv, Docker Compose, Python's python-dotenv). Where a loader diverges, it's called out explicitly, because assuming one loader's behavior applies everywhere is where most of these bugs come from.

• KEY=value, no spaces around =.This isn't enforced everywhere, but it's the convention every example follows, and a stray space before the = is invalid in some parsers and silently included in the key name in others — neither outcome is what you want.
• An unquoted value stops at the first #. Everything from that # onward is a comment, not part of the value — even if the # appears in the middle of what looks like one continuous string. A value that legitimately contains a # (a hex color, a URL fragment, a password) has to be quoted, or it gets silently truncated.
• Single quotes are completely literal. No escape sequences, no variable expansion — API_KEY='a\nb' is the six characters a\nb, backslash and all, not a newline. Single quotes are the right choice when the value itself might contain something that looks like an escape sequence or a variable reference and you want it left exactly alone.
• Double quotes allow escape sequences, and sometimes variable expansion. Inside double quotes, \n becomes an actual newline character and \" becomes a literal quote. Some loaders — Docker Compose among them — also expand ${OTHER_VAR} references inside double-quoted values; plain Node dotenvdoes not, by default. Don't rely on expansion working unless you've confirmed the specific loader supports it.
• Multi-line values need a quoted string that spans lines, not a bare line break. A private key or a multi-line certificate has to be wrapped in quotes with the newlines inside them — an unquoted value simply ends at the first line break, and whatever comes after starts being parsed as a new (probably invalid) key.

# Database
DATABASE_URL=postgres://user:pass@localhost:5432/app

# A value that contains a literal # must be quoted, or it's truncated at the #
HEX_COLOR="#1e293b"

# Single quotes: completely literal, no escapes, no expansion
RAW_TEMPLATE='Hello, ${NAME}! Line1\nLine2 stays literal'

# Double quotes: \n becomes an actual newline
GREETING="Hello,\nworld"

# Multi-line value — quoted, newlines inside the quotes
PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
MIIBVgIBADANBgkqhkiG9w0BAQEFAASCAT8w
-----END PRIVATE KEY-----"

Both of the following produce a .env file that looks entirely correct on a read-through. Neither one throws an error. Both cause a bug that only shows up when the running process reads the value.

A duplicate key — the last one silently wins. There's no uniqueness constraint on .env keys, so defining PORTtwice — once near the top of the file, once further down after a copy-paste from another config — doesn't raise a warning. The loader just keeps overwriting as it reads line by line, and whichever assignment comes last in the file is the one the process gets. If the second definition was added by accident, the effective value is wrong and there's nothing in the file itself pointing at why.

Trailing whitespace after = becomes part of the value.A loader that doesn't trim automatically treats everything between = and the end of the line (or the closing quote) as the value, whitespace included. API_TOKEN=abc123   with two trailing spaces sets API_TOKEN to "abc123  ", not "abc123". It looks identical in an editor, diffs as identical in most viewers that collapse trailing whitespace, and then fails an exact string comparison — a signature check, an API auth header, a feature-flag match — at runtime, with no visible reason why.

PORT=3000
LOG_LEVEL=debug
PORT=4000
API_TOKEN=abc123

→ Effective PORT: 4000 (the first PORT=3000 is silently discarded)
→ Effective API_TOKEN: "abc123  " (two trailing spaces are part of the value)
→ if (token === "abc123") fails — the file "looks" like it says abc123

A .env file is a convention, not a data format — most tools that need config don't read .env directly, they expect JSON, YAML, or a set of shell exports, and something in between has to bridge the gap. A dotenv to json conversion is what you need to feed environment config into a tool that only accepts a JSON config object. Turning the same file into YAML fits a Kubernetes ConfigMap or a CI pipeline's config block. Turning it into shell export statements lets you source it directly in a script, and turning it into docker run -e flags saves retyping every variable by hand on the command line.

An env parser built for this has to apply the quoting and comment rules above correctly, or the conversion just reproduces the same ambiguity in a new format. A trustworthy env file converter also flags the duplicate-key and trailing-whitespace problems while it converts, since those are exactly the mistakes that survive a naive line-by-line pass unnoticed.

GenKitLab's ENV Parser is that dotenv converter: paste a .env file and get JSON, YAML, shell exports, Docker -e flags, or Terraform tfvars out, with duplicate keys and quoting mistakes surfaced before the file reaches a container. It runs entirely client-side — nothing you paste is uploaded anywhere. If the target format is YAML specifically and you want the conversion rules for that format covered in depth, see YAML to JSON and YAML Formatter.