﻿# Dotenv

> Load your .env and get to work

  [Quickstart](#quickstart) [Video](#demo) [SDK](#sdk) [CLI](#cli) [FAQ](#common-questions)

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](https://12factor.net/config).

## Quickstart

Install dotenv in your project.

```bash
npm install dotenv --save
```

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

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

Load dotenv as early as possible in your application.

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

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

```console
$ 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.

```bash
npx dotenv run -- node index.js
```

   Download the [mp4](https://github.com/user-attachments/assets/79395e92-5ce0-430d-b8b5-31631aac25bb) video.

 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.

```javascript
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.

```javascript
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.

```javascript
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

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

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

```bash
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.

```javascript
import 'dotenv/config'
```

### Does dotenv expand variables?

Use [dotenv-expand](https://github.com/dotenvx/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](https://github.com/motdotla/dotenv#readme).

[Changelog](https://github.com/motdotla/dotenv/blob/master/CHANGELOG.md) · [npm](https://www.npmjs.com/package/dotenv) · [GitHub](https://github.com/motdotla/dotenv)
