dotenv vs direnv at a glance
| dotenv | direnv | |
|---|---|---|
| What it is | library (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 into | the app process | your interactive shell |
| When | at app startup | on cd into the directory, unloads on leaving |
| Safety gate | none | direnv allow per file version |
| Can also | expand variables (dotenv-expand) | activate a Python venv, extend PATH, run any shell code |
| Windows | everywhere Node/Python runs | best 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
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
| Scenario | Pick |
|---|---|
App reads process.env / os.environ at runtime | dotenv or node --env-file |
| CLI tools should just work inside the project | direnv |
| Python venv and env vars activated together | direnv (layout python) |
| Team on Windows without WSL | dotenv |
| CI/CD | neither: pipeline secrets |
| Production | neither: 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.envrccontainingdotenv, rundirenv allow. - direnv → dotenv: move shell logic (functions,
PATH, venv activation) into a script; the plainKEY=valuelines 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.