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: 

eval "$(direnv hook bash)"

Then reload your configuration: 

source ~/.bashrc

For zsh users, add this line to your ~/.zshrc file: 

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 (direnv >= 2.31.0)

If you want direnv to automatically recognize and load .env files (in addition to .envrc), you can enable this feature in your direnv.toml configuration file:

  1. Create or edit the file at ~/.config/direnv/direnv.toml.
  2. Add the following:
[global] load_dotenv = true
  • With this setting, direnv will look for and load .env files on top of .envrc files.
  • If both .envrc and .env exist, .envrc takes precedence.
  • Requires direnv version 2.31.0 or newer.
  • See the official documentation for more details.

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).
    • Or, in older direnv versions, add dotenv to your .envrc: 
      dotenv

  • 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:

    • Make sure you are in the directory (or a subdirectory) containing the .envrc or .env and that it is allowed.

  • 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:

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. ↩