Dotenv

Load your .env and get to work. In your app, or before any command.

Get started View on GitHub

Dotenv is a zero-dependency module that loads variables from a .env file into process.env. Keep configuration separate from code, following The Twelve-Factor App.

Quickstart

Install dotenv in your project.

npm install dotenv --save

Create a .env file in the root of your project.

# .env
HELLO="Dotenv"
OPENAI_API_KEY="your-api-key-goes-here"

Load dotenv as early as possible in your application.

// index.js
require('dotenv').config()
// or import 'dotenv/config' // for ESM

console.log(`Hello ${process.env.HELLO}`)

$ node index.js
◇ injected env (2) from .env
Hello Dotenv

That's it. Your variables are now available in process.env.

Prefer the command line?

Dotenv 18 includes a CLI. Load your .env before the command starts, with no dotenv import needed in your app.

npx dotenv run -- node index.js

Watch the 30 second demo

SDK

Three functions for loading, parsing, and populating environment variables.

config

Read your .env file, parse its contents, and assign the values to process.env. Returns an object with parsed values, or an error if loading fails.

const dotenv = require('dotenv')
const result = dotenv.config({ path: ['.env.local', '.env'] })

if (result.error) throw result.error
console.log(result.parsed)

Option	Default	What it does
path	.env	File path, file URL, or an array of paths. Defaults to .env in the current working directory.
quiet	false	Suppress the injected environment variables message.
encoding	utf8	Encoding of your .env file.
debug	false	Enable debug logging.
override	false	Overwrite existing variables. Later files win when loading multiple files.
fast	false	Use the faster character-scanner parser.
processEnv	process.env	Write values to another object instead.

By default, existing environment variables take precedence. Across multiple files, the first value wins. With override enabled, the last value wins.

parse

Turn a string or Buffer into an object of keys and values, without changing your environment. Pass debug: true as an option for diagnostic output.

const dotenv = require('dotenv')
const parsed = dotenv.parse('HELLO="Dotenv"')
// { HELLO: 'Dotenv' }

populate

Copy parsed values into a target object. Supports override and debug options, both false by default.

const dotenv = require('dotenv')
const target = { HELLO: 'World' }

dotenv.populate(target, { HELLO: 'Dotenv' }, { override: true })
console.log(target.HELLO) // Dotenv

CLI

Run scripts, tests, or any executable with variables from your .env file. Use npx dotenv, or dotenv directly in npm scripts.

run

npx dotenv run [options] -- <command> [args...]

Select another file with -f, or repeat it to load several files in order.

npx dotenv run -f .env.local -- node index.js
npx dotenv run -f .env.local -f .env -- npm test

Put dotenv options before the command. The -- separator is optional; everything after the command is passed through as its arguments.

Option	What it does
-f, --file <paths>	Load files in order. Repeat the flag or separate paths with commas. Defaults to .env.
-q, --quiet	Suppress the injected environment variables message.
--debug	Enable debug logging.
--override	Overwrite existing variables. Later files win.
--fast	Use the faster character-scanner parser.
-h, --help	Show help. Also available as dotenv --help.

Without --override, existing environment variables take precedence and the first value found across files wins. The CLI forwards your command's exit status. A missing default .env is allowed; an explicitly selected missing file stops the command from running.

Environment defaults

These defaults apply to both config() and the CLI. Explicit options or flags take precedence.

Variable	Default
DOTENV_PATH	.env
DOTENV_ENCODING	utf8
DOTENV_QUIET	false
DOTENV_DEBUG	false
DOTENV_OVERRIDE	false
DOTENV_FAST	false

The legacy DOTENV_CONFIG_* names remain fallbacks when the corresponding DOTENV_* variable is unset. For boolean settings, false, 0, no, off, and an empty value disable the setting.

A few common questions

Should I commit my .env file?

Keep plaintext secrets out of version control. Use dotenvx if you want to encrypt your .env files and commit them safely while keeping private keys separate.

What about ESM?

Import dotenv/config before modules that read environment variables, or use the CLI to load variables before Node starts.

import 'dotenv/config'

Does dotenv expand variables?

Use dotenv-expand for variable expansion, or dotenvx for expansion, command substitution, and encrypted .env files.

For parsing rules, framework examples, and more answers, see the full README.

Changelog · npm · GitHub