# dotenv-expand
> Expand environment variables using dotenv
Latest version **1000.0.0** (published 2026-07-29) · BSD-3-Clause license · 0 weekly downloads
## Install
```sh
npm install dotenv-expand
pnpm add dotenv-expand
yarn add dotenv-expand
bun add dotenv-expand
```
## Health
**Score 70/100 (B)** — status: active.
Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.
Warnings: low downloads.
## Facts
| | |
|---|---|
| Version | 1000.0.0 |
| Published | 2026-07-29 |
| First published | 2016-01-21 |
| Weekly downloads | 0 |
| License | BSD-3-Clause |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=16 |
| Dependencies | 0 |
| Unpacked size | 290.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1057 |
| Author | motdotla |
| Maintainers | motdotla |
| Keywords | dotenv, expand, variables, interpolation, substitution, env, .env |
## Links
- npm: https://www.npmjs.com/package/dotenv-expand
- Repository: https://github.com/dotenvx/dotenv-expand
- Homepage: https://github.com/dotenvx/dotenv-expand#readme
- Issues: https://github.com/dotenvx/dotenv-expand/issues
- Funding: https://dotenvx.com
- npm.io page: https://npm.io/package/dotenv-expand
## Alternatives
- [replicas-cli](https://npm.io/package/replicas-cli.md) — 3.0K weekly downloads
- [env-contract](https://npm.io/package/env-contract.md) — 133 weekly downloads
- [@openveo/api](https://npm.io/package/@openveo/api.md) — 61 weekly downloads
- [@ryniaubenpm2/cumque-error-reiciendis](https://npm.io/package/@ryniaubenpm2/cumque-error-reiciendis.md) — 54 weekly downloads
- [ts-global-type-extra](https://npm.io/package/ts-global-type-extra.md) — 11 weekly downloads
## Recent versions
- 1000.0.0 (latest) — 2026-07-29
- 13.0.0 — 2026-04-17
- 12.0.3 — 2025-09-02
- 12.0.2 — 2025-04-17
- 12.0.1 — 2024-11-18
- 12.0.0 — 2024-11-16
- 11.0.7 — 2024-11-13
- 11.0.6 — 2024-02-18
- 11.0.5 — 2024-02-18
- 11.0.4 — 2024-02-15
- 11.0.3 — 2024-02-11
- 11.0.2 — 2024-02-10
- 11.0.1 — 2024-02-10
- 11.0.0 — 2024-02-10
- 10.0.0 — 2022-12-16
- … 15 more at https://npm.io/package/dotenv-expand/versions
## README
> If you have found dotenv-expand useful, consider checking out [dotenvx](https://github.com/dotenvx/dotenvx) for encrypting your `.env` files. Thank you for using dotenv. 🙏
# dotenv-expand [](https://www.npmjs.com/package/dotenv-expand) [](https://www.npmjs.com/package/dotenv-expand)
Dotenv-expand is a zero-dependency module that adds variable expansion, command substitution, and encrypted value support on top of [dotenv](https://github.com/motdotla/dotenv).
## Usage
Install it alongside dotenv.
```sh
npm install dotenv dotenv-expand --save
```
Create a `.env` file in the root of your project:
```ini
# .env
USERNAME="dotenv"
DATABASE_URL="postgres://${USERNAME}@localhost/my_database"
```
As early as possible in your application, configure dotenv and expand its result:
```javascript
// index.js
const dotenv = require('dotenv')
const dotenvExpand = require('dotenv-expand')
dotenvExpand.expand(dotenv.config())
console.log(process.env.DATABASE_URL)
```
```sh
$ 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](https://github.com/dotenvx/dotenvx) instead. It includes expansion, command substitution, and encrypted `.env` support across languages and platforms:
>
> ```sh
> dotenvx run -- node your_script.js
> ```
Use Node's `--require` (`-r`) option to load and expand `.env` before your application starts:
```sh
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:
```sh
node -r dotenv-expand/config your_script.js dotenv_config_path=/custom/path/to/.env
```
Or as environment variables:
```sh
DOTENV_CONFIG_ENCODING=latin1 node -r dotenv-expand/config your_script.js
```
Command-line arguments take precedence over environment variables.
pnpm
```sh
pnpm add dotenv dotenv-expand
```
Command Substitution
Use `$(command)` to replace an expression with the command's output:
```ini
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](https://dotenvx.com) to encrypt your `.env` file. dotenv-expand automatically decrypts `encrypted:` values when `DOTENV_PRIVATE_KEY` is set:
```sh
DOTENV_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](https://dotenvx.com/dotenvx.pdf?v=README) for more details.
Custom Process Environment
Use `processEnv` to write expanded values to an object other than `process.env`:
```javascript
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:
```ini
BASIC="basic"
BRACED=${BASIC}
UNBRACED=$BASIC
DEFAULT=${MISSING:-default}
ALTERNATE=${BASIC:+alternate}
```
See the complete [interpolation rules](https://dotenvx.com/docs/env-file#interpolation).
What rules does the expansion engine follow?
See a full list of rules [here](https://dotenvx.com/docs/env-file#interpolation).
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](https://dotenvx.com) to encrypt your `.env` file. dotenv-expand automatically decrypts `encrypted:` values when `DOTENV_PRIVATE_KEY` is set.
```sh
DOTENV_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](https://dotenvx.com/dotenvx.pdf?v=README) 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](https://dotenvx.com) 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](https://dotenvx.com) and ship an encrypted `.env` file with your code, allowing safe expansion at runtime.
How can I override an existing environment variable?
Use [dotenvx](https://dotenvx.com), 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.