How to install direnv: .envrc basics, direnv allow, and auto-load env vars

Install direnv, author .envrc, allow once, auto-load per directory.

Every repo wants its own API keys, database URLs, and PATH tweaks, but manually sourceing .env files gets old. direnv reads .envrc in a project folder: cd in to load environment variables, cd out to unload. This guide covers install on macOS/Linux, shell hooks, .envrc basics, running direnv allow in the project directory, and automatic load/unload for hereink readers who juggle many repos in the terminal.

The query is how to install direnv and write .envrc to load project env vars automatically. You should finish with direnv installed, a first .envrc, direnv allow at the repo root, and variables appearing when you enter the directory and disappearing when you leave.

What direnv fixes

Upstream: github.com/direnv/direnv, docs at direnv.net. Run direnv version after install.

Install direnv

1. 1
   macOS (Homebrew)

   brew install direnv. Verify with which direnv and direnv version.

2. 2
   Linux (distro packages)

   Debian/Ubuntu: sudo apt update && sudo apt install direnv. Fedora: sudo dnf install direnv. Arch: sudo pacman -S direnv.

3. 3
   Shell hook (required)

   Add to ~/.zshrc or ~/.bashrc: eval "$(direnv hook zsh)" (use bash for bash). Open a new terminal or source the file.

4. 4
   fish

   In ~/.config/fish/config.fish: direnv hook fish | source. See official docs for other shells.

.envrc basics

.envrc is a shell snippet at the project root (or a subdirectory). Common patterns:

export API_BASE=https://api.staging.example.com
export NODE_ENV=development

PATH_add ./bin

dotenv_if_exists

Do not commit real tokens. Teams can commit non-secret defaults in .envrc and keep secrets in local .env loaded via dotenv_if_exists.

Allow in the project directory

The first time you enter a folder with .envrc, direnv blocks execution until you explicitly trust the file:

cd ~/projects/my-app
# direnv: error .envrc is blocked. Run `direnv allow` to approve its content.

direnv allow
# direnv: loading ~/projects/my-app/.envrc
echo $API_BASE

direnv allow stores a hash whitelist under .direnv/. After you edit .envrc, run direnv allow again. That is intentional: a cloned repo cannot silently change your environment.

Automatic load and unload

With the hook installed, you do not need manual source each time:

cd ~/projects/my-app    # loads .envrc
env | grep API_BASE

cd ~                    # unloads project vars
env | grep API_BASE     # should be empty

Nested directories: a child .envrc applies when you enter that path. Monorepos often use a root .envrc with PATH_add for shared tooling—see source_up in direnv docs.

vs manual source .env

Fits

Switching repos, per-project PATH, staging vs prod endpoints tied to folders.

Does not fit

One global export forever, or CI images—set env in Dockerfile or workflow instead.