direnv Installation Reference

direnv Installation Reference

Complete installation and shell configuration guide for all platforms.

Installation Methods

macOS

Homebrew (Recommended):

brew install direnv

MacPorts:

sudo port install direnv

Nix:

nix-env -i direnv

Linux

Debian/Ubuntu:

sudo apt update
sudo apt install direnv

Fedora:

sudo dnf install direnv

Arch Linux:

sudo pacman -S direnv

Alpine:

apk add direnv

Nix:

nix-env -i direnv

Binary Installer (Any Linux):

curl -sfL https://direnv.net/install.sh | bash

From Source:

# Requires Go 1.16+
git clone https://github.com/direnv/direnv
cd direnv
make
sudo make install

Windows

Scoop:

scoop install direnv

Chocolatey:

choco install direnv

Git Bash/MSYS2:

pacman -S direnv

WSL:

Use Linux installation methods.

Verify Installation

direnv version
# Expected: 2.32.0 or higher

Shell Hook Configuration

The shell hook is required for direnv to work. It must be added to your shell's configuration file.

Zsh

Add to ~/.zshrc:

eval "$(direnv hook zsh)"

With Oh My Zsh:

Add direnv to your plugins array in ~/.zshrc:

plugins=(git docker direnv)

With Prezto:

Enable the direnv module in ~/.zpreztorc:

zstyle ':prezto:load' pmodule \
  'environment' \
  'terminal' \
  'editor' \
  'history' \
  'directory' \
  'spectrum' \
  'utility' \
  'completion' \
  'prompt' \
  'direnv'

Bash

Add to ~/.bashrc:

eval "$(direnv hook bash)"

For macOS with bash, also add to ~/.bash_profile if it sources ~/.bashrc.

Fish

Add to ~/.config/fish/config.fish:

direnv hook fish | source

PowerShell

Add to PowerShell profile ($PROFILE):

Invoke-Expression "$(direnv hook pwsh)"

Elvish

Add to ~/.elvish/rc.elv:

eval (direnv hook elvish | slurp)

Tcsh

Add to ~/.cshrc:

eval `direnv hook tcsh`

Nushell

Add to $nu.config-path:

$env.config = ($env.config | merge {
  hooks: {
    pre_prompt: [{ ||
      if (which direnv | is-empty) {
        return
      }
      direnv export json | from json | default {} | load-env
    }]
  }
})

POSIX Shell

Add to ~/.profile:

eval "$(direnv hook sh)"

Applying Shell Configuration

After adding the hook, apply the changes:

# Zsh
source ~/.zshrc

# Bash
source ~/.bashrc

# Fish
source ~/.config/fish/config.fish

Or simply restart your terminal.

Hook Placement Guidelines

1. Place at the end - The hook should be the last line in your config, after:

   • Other shell extensions (rvm, nvm, pyenv)
   • Prompt customizations
   • Path modifications

2. After version managers - If using asdf, rbenv, pyenv, nvm:

   # ~/.zshrc
   
   # Version managers first
   eval "$(pyenv init -)"
   eval "$(rbenv init -)"
   
   # direnv last
   eval "$(direnv hook zsh)"
   

Updating direnv

Homebrew

brew upgrade direnv

Self-update (binary install)

direnv version  # Check current
curl -sfL https://direnv.net/install.sh | bash  # Reinstall latest

Package Managers

# Debian/Ubuntu
sudo apt update && sudo apt upgrade direnv

# Fedora
sudo dnf upgrade direnv

# Arch
sudo pacman -Syu direnv

Global Configuration

Create ~/.config/direnv/direnv.toml:

[global]
# Hide environment diff in output
hide_env_diff = false

# Load .env files
load_dotenv = true

# Warn when using old stdlib functions
warn_timeout = "5s"

# Disable loading .envrc globally (emergency)
# disable_stdin = true

[whitelist]
# Auto-allow specific paths (use with caution)
# prefix = ["/home/user/trusted-projects"]
# exact = ["/home/user/specific-project/.envrc"]

Verification

After installation, verify everything works:

# 1. Check version
direnv version

# 2. Create test directory
mkdir /tmp/direnv-test && cd /tmp/direnv-test

# 3. Create .envrc
echo 'export TEST_VAR=hello' > .envrc

# 4. Allow it
direnv allow

# 5. Verify variable is set
echo $TEST_VAR
# Should output: hello

# 6. Leave directory and verify unloading
cd /tmp
echo $TEST_VAR
# Should be empty

# 7. Cleanup
rm -rf /tmp/direnv-test

Troubleshooting Installation

Hook Not Working

1. Verify hook is in correct config file:

   # Zsh
   grep "direnv hook" ~/.zshrc
   
   # Bash
   grep "direnv hook" ~/.bashrc
   

2. Source the config:

   source ~/.zshrc  # or ~/.bashrc
   

3. Restart terminal completely

4. Check for conflicts:

   # Look for duplicate hooks
   grep -r "direnv" ~/.*rc ~/.*profile 2>/dev/null
   

Permission Denied

# Make direnv executable
chmod +x $(which direnv)

Old Version Warnings

# Update to latest
brew upgrade direnv  # macOS
sudo apt upgrade direnv  # Ubuntu

PATH Issues

Ensure direnv is in PATH:

which direnv
# Should return path like /usr/local/bin/direnv

# If not found, add to PATH
export PATH="/usr/local/bin:$PATH"  # Add to shell config

Uninstallation

Homebrew

brew uninstall direnv

Manual

# Remove binary
sudo rm $(which direnv)

# Remove configuration
rm -rf ~/.config/direnv
rm -rf ~/.local/share/direnv

# Remove hook from shell config (edit manually)

Remember to remove the hook from your shell configuration files.