Documentation
Documentation

.env

The .env file separates your secrets from code.

Format

.env files use a simple format – key/values separated by an equal sign.

.env

# .env
STRIPE_API_KEY=scr_12345
TWILIO_API_KEY=abcd1234

Then it is loaded into your application code using process.env.

console.log('Hello ' + process.env.HELLO)

It's a convenient and widely adopted format for separating your secrets and config from your code.

Keys

For the sake of portability (and sanity), environment variable names (keys) must consist solely of letters, digits, and the underscore ( _ ) and must not begin with a digit. In regex-speak, the names must match the following pattern:

[a-zA-Z_]+[a-zA-Z0-9_]*

Example keys

DATABASE_URL  # ok
foobar        # ok (but not recommended. use upcase)
NO-WORK       # <-- invalid !!!
ÜBER          # <-- invalid !!!
2MUCH         # <-- invalid !!!

credit: dotenvy

Values

Values are to the right of the equals sign. They may be quoted. Using single quotes will prevent variables from being interpolated.

SIMPLE=xyz123
INTERPOLATED="Multiple\nLines"
NON_INTERPOLATED='raw text without variable interpolation'
MULTILINE = `long text here,
e.g. a private SSH key`

credit: dotenvy

Syntax

The following syntax rules apply to environment files:

  • Lines beginning with # are processed as comments and ignored.
  • Blank lines are ignored.
  • Unquoted and double-quoted (") values have interpolation applied.
  • Each line represents a key-value pair. Values can optionally be quoted.
    • VAR=VAL -> VAL
    • VAR="VAL" -> VAL
    • VAR='VAL' -> VAL
  • Inline comments for unquoted values must be preceded with a space.
    • VAR=VAL # comment -> VAL
    • VAR=VAL# not a comment -> VAL# not a comment
  • Inline comments for quoted values must follow the closing quote.
    • VAR="VAL # not a comment" -> VAL # not a comment
    • VAR="VAL" # comment -> VAL
  • Single-quoted (') values are used literally.
    • VAR='$OTHER' -> $OTHER
    • VAR='${OTHER}' -> ${OTHER}
  • Quotes can be escaped with .
    • VAR='Let\'s go!' -> Let's go!
    • VAR="{\"hello\": \"json\"}" -> {"hello": "json"}
  • Common shell escape sequences including \n, \r, \t, and \\ are supported in double-quoted values.
    • VAR="some\tvalue" -> some value
    • VAR='some\tvalue' -> some\tvalue
    • VAR=some\tvalue -> some\tvalue

Comments

The hash-tag # symbol denotes a comment when on its own line or when it follows a quoted value. It is not treated as a comment when it appears within quotes.

# This is a comment
SECRET_KEY=YOURSECRETKEYGOESHERE # also a comment
SECRET_HASH="something-with-a-hash-#-this-is-not-a-comment"

credit: dotenvy

Interpolation

Interpolation (also known as variable expansion) is supported in environment files. Interpolation is applied for unquoted and double-quoted values. Both braced (${VAR}) and unbraced ($VAR) expressions are supported.

  • Direct interpolation
    • ${VAR} -> value of VAR
  • Default value
    • ${VAR:-default} -> value of VAR if set and non-empty, otherwise default
    • ${VAR-default} -> value of VAR if set, otherwise default
  • Alternative value
    • ${VAR:-alternate} -> value of alternate if VAR is set and non-empty, otherwise empty ''
    • ${VAR-alternate} -> value of alternate if VAR is set and non-empty, otherwise empty ''

Command Substitution

Add the output of a command to one of your variables in your .env file. Command substitution is applied for unquoted and double-quoted values.

  • Direct substitution
    • $(whoami) -> value of $ whoami

.env

DATABASE_URL="postgres://$(whoami)@localhost/my_database"

Encryption

.env files can be extended to support encryption. Preface each value with encrypted: followed by a secp256k1 encrypted string.

.env

#/-------------------[DOTENV_PUBLIC_KEY]--------------------/
#/            public-key encryption for .env files          /
#/       [how it works](https://dotenvx.com/encryption)     /
#/----------------------------------------------------------/
DOTENV_PUBLIC_KEY="03f98bf6e00bce6fdb933bc47738d671dffb75a916fa8c89854bdfa3483902632f"

# .env
HELLO="encrypted:BCV9qZmblsUm77IxgrEqY9t67qDVWQZg6jpogQhBWa9SaOCtvheEQ5/eUfPCigQ7KB6vN//6vFE+2+orG7LmUorWhe1JapWct6Dz58IY6mXi+ONs51F7TSed6R/T9e+lDBWYH04p"

Additionally, include the DOTENV_PUBLIC_KEY inside the .env file and commit .env to code. It's now encrypted, safe, and recommended to do so.

Use dotenvx to auto-generate this format extension.

$ dotenvx encrypt
encrypted (.env)

History

The .env file format was introduced by Heroku in 2012 and popularized by the dotenv node and dotenv ruby libraries in 2013.

Apps sometimes store config as constants in the code. This is a violation of twelve-factor, which requires strict separation of config from code. Config varies substantially across deploys, code does not.

A litmus test for whether an app has all config correctly factored out of the code is whether the codebase could be made open source at any moment, without compromising any credentials. The Twelve-Factor App

Other languages, frameworks, platforms, and infra tools like Docker followed soon after – implementing environment variable support. Today, it has become an industry standard.

Encryption support was introduced May of 2024.