Skip to content

Install and configure direnv for environment management

Why we need direnv

When working on multiple projects, each one often needs its own set of environment variables. Managing these manually is error-prone and tedious. direnv1 automatically loads and unloads environment variables as you move between different project directories, making it much easier to manage project-specific configurations.

How to install direnv

For macOS:

brew install direnv

For Linux:

# Ubuntu/Debian
sudo apt-get install direnv

# Fedora
sudo dnf install direnv

Verify that direnv is installed and available in your PATH:

which direnv
# Should show something like /usr/local/bin/direnv

How to configure direnv

After installation, you need to hook direnv into your shell.

For bash users, add this line to your ~/.bashrc file (the official setup docs put it at the end of the file so it runs after other extensions that change the prompt):

eval "$(direnv hook bash)"

Then reload your configuration:

source ~/.bashrc

For zsh users, add this line to your ~/.zshrc file (again, the hook docs recommend placing it at the end):

eval "$(direnv hook zsh)"

Then reload your configuration:

source ~/.zshrc

Now direnv is ready to use. To verify it's working:

# Create a test directory
mkdir ~/direnv-test && cd ~/direnv-test

# Create a basic .envrc file
echo 'export TEST_VAR="Hello, direnv!"' > .envrc

# Allow the .envrc file
direnv allow .

# Verify the variable is set
echo $TEST_VAR
# Should output: Hello, direnv!

When you leave the directory, direnv will automatically unload these variables, keeping your environment clean and organized.

Loading .env files automatically

Turn on load_dotenv when you want .env picked up next to .envrc. The knob is documented under direnv.toml(1) — load_dotenv; it requires direnv 2.31.0 or newer.

  1. Create or edit $XDG_CONFIG_HOME/direnv/direnv.toml (typically ~/.config/direnv/direnv.toml).
  2. Add the following:
[global]
load_dotenv = true
  • direnv.net describes cwd-and-parent traversal for .envrc; enabling load_dotenv folds .env into that workflow with the same allow/deny checks.
  • direnv.toml(1) phrases it as .env files loading on top of .envrc, with .envrc chosen first when both filenames exist beside each other.

Troubleshooting

direnv not loading environment variables

  • Check if direnv is hooked into your shell:

  • For bash, your ~/.bashrc should have:

    eval "$(direnv hook bash)"

  • For zsh, your ~/.zshrc should have:

    eval "$(direnv hook zsh)"

  • After editing, restart your shell.

  • .envrc or .env is not allowed:

  • When you create or modify a .envrc or .env, direnv will block it for security.

  • Run:

    direnv allow .

    to allow it.

  • .env file not loaded:

  • Make sure you have load_dotenv = true in your direnv.toml (see above).

  • Changes to .envrc or .env not taking effect:

  • Run:

    direnv reload

  • Or simply cd out and back into the directory.

  • Environment variables not showing up:

  • Direnv resolves .envrc / .env by scanning your current directory and parents (direnv(1)). Confirm an allowed file lives on $PWD or one of those parents.

  • direnv not installed or not in PATH:

  • Run:

    which direnv

  • If not found, install direnv and ensure it’s in your PATH.

  • Shell not supported:

  • Check direnv’s hook documentation for your shell’s setup instructions.

Common error messages

  • ".envrc is not allowed":
  • Run direnv allow . in the directory.
  • "direnv: command not found":
  • Install direnv and ensure it’s in your PATH.
  • "Environment variable not set":
  • Check your .envrc or .env for typos and ensure the file is allowed.

  1. direnv is an extension for your shell that loads and unloads environment variables depending on your current directory. Learn more about it at direnv.net. ↩