compareBy Aliniyaz Mamat · updated

dotenv vs direnv: which env loader should you use?

dotenv vs direnv: dotenv loads a .env file into your app's process when it starts; direnv loads an .envrc into your shell whenever you cd into a project. They solve different problems, and many teams use both on development machines.

Key takeaways

  • ✓dotenv is a library inside the app; the shell that started the app never sees the values.
  • ✓direnv is a shell hook: psql, redis-cli, pytest and scripts all see the project's variables automatically.
  • ✓direnv only loads an .envrc after direnv allow, and asks again whenever the file changes.
  • ✓One line in .envrc, dotenv, makes direnv read the same .env your app uses: no duplicate values.
  • ✓Neither belongs in production: hosts and secrets managers inject variables there.

dotenv vs direnv at a glance

dotenvdirenv
What it islibrary (Node.js, Python, Ruby, Go, PHP ports)shell extension (bash, zsh, fish and others)
File.env (KEY=value).envrc (shell script, can call dotenv)
Loads intothe app processyour interactive shell
Whenat app startupon cd into the directory, unloads on leaving
Safety gatenonedirenv allow per file version
Can alsoexpand variables (dotenv-expand)activate a Python venv, extend PATH, run any shell code
Windowseverywhere Node/Python runsbest via WSL

What dotenv does

// server.js
import "dotenv/config";
console.log(process.env.DATABASE_URL); // set

// in the terminal that started it:
// $ echo $DATABASE_URL   → empty; dotenv only touched the Node process

On Node.js 20.6+ you don't even need the package: node --env-file=.env server.js. Setup per framework: how to use dotenv.

What direnv does

$ cd ~/projects/api
direnv: loading ~/projects/api/.envrc
direnv: export +DATABASE_URL +JWT_SECRET
$ echo $DATABASE_URL
postgres://localhost/api
$ cd ..
direnv: unloading

Every command in that directory now sees the right values without source .env or wrapping commands. Install it from your package manager (brew install direnv, apt install direnv) and add the hook to your shell config (eval "$(direnv hook zsh)").

Using them together

.envrc
dotenv_if_exists .env          # export .env into the shell (same file the app reads)
layout python                  # create/activate a virtualenv (Python projects)
PATH_add node_modules/.bin     # local CLIs on PATH

Now npm run dev reads .env through dotenv, and psql in the same terminal reaches the same database because direnv exported DATABASE_URL. Keep both .env and .envrc out of git if they contain secrets (how to hide .env from git); an .envrc that only calls dotenv can be committed.

When to use which

ScenarioPick
App reads process.env / os.environ at runtimedotenv or node --env-file
CLI tools should just work inside the projectdirenv
Python venv and env vars activated togetherdirenv (layout python)
Team on Windows without WSLdotenv
CI/CDneither: pipeline secrets
Productionneither: host settings or a secrets manager

Solo projects: start with dotenv. Teams or anyone running database CLIs against a dev database daily: add direnv on top. For production config, see dotenv vs secrets manager.

Switching between them

  • dotenv → direnv: keep .env, add an .envrc containing dotenv, run direnv allow.
  • direnv → dotenv: move shell logic (functions, PATH, venv activation) into a script; the plain KEY=value lines go into .env. Check the result with the .env validator.

Frequently asked questions

Can direnv load a .env file directly?

Yes. direnv's standard library has dotenv (and dotenv_if_exists), so one line in .envrc loads the same .env your app reads.

Does direnv work on Windows?

It's built for Unix shells; on Windows the reliable route is WSL. Teams on native Windows usually stick with dotenv or node --env-file.

Is direnv's allow-list a real security boundary?

Yes. direnv stores a hash of each allowed .envrc outside the repository; if the file changes (e.g. after pulling a branch), it refuses to load it until you run direnv allow again.

Can I use direnv in Docker or a devcontainer?

direnv hooks into your host shell, so it doesn't affect Docker builds or running containers. Inside a devcontainer, install it in the container image if you want the same behaviour there.

Do I need both?

No. dotenv alone covers the app. direnv is worth adding when you often run tools outside the app (database shells, scripts, test runners) that need the same variables.

Related tools

Continue reading