direnv - Automatic Environment Variables Per Directory

Switching between projects means juggling environment variables. AWS credentials for Project A, different Node version for Project B, custom paths for Project C... direnv loads the right environment automatically when you cd into a directory.

🔐

Environment Per Directory

Create a .envrc file in any project. Variables load when you enter, unload when you leave. No more polluting your global shell config.

How direnv Works

direnv hooks into your shell and watches for .envrc files. The magic happens automatically:

direnv automatically loads environment variables when entering a directory and unloads them when leaving

Key Features

🔄

Auto-load on cd

Environment loads instantly when you enter a directory. No need to source files manually.

📁

Per-Project Configs

Each project has its own .envrc. Different AWS profiles, Node versions, API keys per project.

🔒

Secure Allowlisting

New or modified .envrc files require explicit approval. Prevents malicious code execution.

🐚

Shell Integration

Works with bash, zsh, fish, tcsh, and more. One-line hook in your shell config.

Practical Examples

Install direnv and hook it into your shell:

# Install on macOS
brew install direnv

# Install on Ubuntu/Debian
sudo apt install direnv

# Add to ~/.zshrc (or ~/.bashrc for bash)
eval "$(direnv hook zsh)"

Basic .envrc examples:

# Simple environment variables
export API_KEY="sk_live_abc123xyz"
export DATABASE_URL="postgres://user:pass@localhost:5432/mydb"
export NODE_ENV="development"

# Extend PATH for project-specific binaries
export PATH="$PWD/bin:$PWD/node_modules/.bin:$PATH"

# Load secrets from external file (not in git)
dotenv .env.local

# Use specific Node version with nvm
use node 18.17.0

# Python virtualenv auto-activation
layout python3
# Creates and activates .direnv/python-3.x venv automatically

# AWS profile switching
export AWS_PROFILE="production"
export AWS_DEFAULT_REGION="us-west-2"

Why Developers Love It

✓ No More source .env - Stop manually loading env files. Just cd into your project.
✓ Clean Shell Environment - Variables unload when you leave. No leftover configs from other projects.
✓ Security First - Won't run untrusted .envrc files. Requires explicit direnv allow.
✓ Git-Friendly - Add .envrc with non-secret configs to git. Keep secrets in .env.local (gitignored).
✓ IDE Integration - Works with VS Code, JetBrains, and terminal-based editors seamlessly.

Cheatsheet

Common patterns for different project types:

Project Type	.envrc Pattern	What It Does
Node.js	`layout node`	Adds node_modules/.bin to PATH
Python	`layout python3`	Creates/activates virtualenv
Ruby	`layout ruby`	Sets up bundler path
Go	`layout go`	Sets GOPATH to project
Load .env	`dotenv`	Sources .env file
Custom .env	`dotenv .env.local`	Sources specific env file
nvm	`use node`	Uses Node version from .nvmrc
Parent .envrc	`source_up`	Inherits from parent directory

Pro Tips

Advanced direnv patterns for power users:

📦

Load Secrets from 1Password/Vault

export API_KEY=$(op read "op://Vault/API Key/credential")

Fetch secrets at load time. Never store them in files.

🔗

Conditional Loading

if [ -f .env.local ]; then
  dotenv .env.local
fi

Only load files that exist. Great for optional local overrides.

🎯

Project-Specific PATH

PATH_add bin
PATH_add scripts
PATH_add node_modules/.bin

Use PATH_add instead of manual PATH manipulation. Safer and cleaner.

🌐

Global .direnvrc Functions

Create ~/.config/direnv/direnvrc to define reusable functions across all projects.

# In ~/.config/direnv/direnvrc
use_nvm() {
  source ~/.nvm/nvm.sh
  nvm use
}

🔄

Watch Additional Files

watch_file .env
watch_file .nvmrc

Reload environment when these files change, not just .envrc.

Getting Started

1

Install direnv

Use your package manager: brew install direnv or apt install direnv
2

Hook into Your Shell

Add eval "$(direnv hook zsh)" to your shell config. Restart your terminal.
3

Create .envrc

In your project directory, create a .envrc file with your environment variables.
4

Allow the File

Run direnv allow to approve the new .envrc. Your env loads automatically!

Try direnv Today

Stop manually sourcing env files. Let your directory structure manage your environment automatically.

Read the Docs

Launch Offer