If you have found dotenv-expand useful, consider checking out dotenvx for encrypting your .env files. Thank you for using dotenv. 🙏
dotenv-expand 
Dotenv-expand is a zero-dependency module that adds variable expansion, command substitution, and encrypted value support on top of dotenv.
Usage
Install it alongside dotenv.
npm install dotenv dotenv-expand --save
Create a .env file in the root of your project:
# .env
USERNAME="dotenv"
DATABASE_URL="postgres://${USERNAME}@localhost/my_database"
As early as possible in your application, configure dotenv and expand its result:
// index.js
const dotenv = require('dotenv')
const dotenvExpand = require('dotenv-expand')
dotenvExpand.expand(dotenv.config())
console.log(process.env.DATABASE_URL)
$ node index.js
postgres://dotenv@localhost/my_database
That's it. process.env now contains the expanded values from your .env file.
Advanced
Preload
Consider using dotenvx instead. It includes expansion, command substitution, and encrypted .env support across languages and platforms:
dotenvx run -- node your_script.js
Use Node's --require (-r) option to load and expand .env before your application starts:
node -r dotenv-expand/config your_script.js
The preload entry is self-contained; you do not need to separately install dotenv.
Configuration options can be passed as command-line arguments:
node -r dotenv-expand/config your_script.js dotenv_config_path=/custom/path/to/.env
Or as environment variables:
DOTENV_CONFIG_ENCODING=latin1 node -r dotenv-expand/config your_script.js
Command-line arguments take precedence over environment variables.
pnpm
pnpm add dotenv dotenv-expand
Command Substitution
Use $(command) to replace an expression with the command's output:
NODE_VERSION=$(node --version)
Only use command substitution with .env files you trust. Commands run with the permissions of the current process.
Encrypted Values
Use dotenvx to encrypt your .env file. dotenv-expand automatically decrypts encrypted: values when DOTENV_PRIVATE_KEY is set:
DOTENV_PRIVATE_KEY="<private key>" node -r dotenv-expand/config your_script.js
Keep the private key separate from the encrypted .env file—for example, in your cloud platform's secrets manager. Read the dotenvx whitepaper for more details.
Custom Process Environment
Use processEnv to write expanded values to an object other than process.env:
const dotenvExpand = require('dotenv-expand')
const myEnv = {}
dotenvExpand.expand({
processEnv: myEnv,
parsed: {
HELLO: 'World'
}
})
console.log(myEnv.HELLO) // World
console.log(process.env.HELLO) // undefined
Interpolation Syntax
dotenv-expand supports braced and unbraced expansion, default values, and alternate values:
BASIC="basic"
BRACED=${BASIC}
UNBRACED=$BASIC
DEFAULT=${MISSING:-default}
ALTERNATE=${BASIC:+alternate}
See the complete interpolation rules.
FAQ
What rules does the expansion engine follow?
See a full list of rules here.
How does command substitution work?
Use $(command) in your .env file. dotenv-expand runs the command and replaces the expression with its output. See the Command Substitution example under Advanced.
How does encryption work?
Use dotenvx to encrypt your .env file. dotenv-expand automatically decrypts encrypted: values when DOTENV_PRIVATE_KEY is set.
DOTENV_PRIVATE_KEY="<private key>" node -r dotenv-expand/config your_script.js
Keep the private key separate from the encrypted .env file—for example, in your cloud platform's secrets manager. Read the dotenvx whitepaper for more details.
Is it safe to commit an encrypted `.env` file?
Yes, as long as the corresponding DOTENV_PRIVATE_KEY is stored separately and never committed with it. Use dotenvx to create and manage the encrypted file.
How can I avoid expanding pre-existing envs?
As of v12.0.0 dotenv-expand no longer expands process.env.
If you need this ability, use dotenvx and ship an encrypted .env file with your code, allowing safe expansion at runtime.
How can I override an existing environment variable?
Use dotenvx, as dotenv-expand does not support this.
dotenv-expand is a separate module (without knowledge of the loading of process.env and the .env file) and so cannot reliably know what to override.
Docs
Expand
expand expands, evaluates, and decrypts values in a dotenv result:
const dotenvExpand = require('dotenv-expand')
const result = dotenvExpand.expand({
parsed: {
BASIC: 'basic',
BASIC_EXPAND: '${BASIC}',
BASIC_EXPAND_SIMPLE: '$BASIC'
}
})
console.log(result.parsed)
Options
processEnv
Default: process.env
Specify an object to read existing values from and write expanded values to.
parsed
The parsed key-value object to expand. This is normally the result of dotenv.config().
Contributing
See CONTRIBUTING.md.
CHANGELOG
See CHANGELOG.md.
Who's using dotenv-expand?
These npm modules depend on it.
