Direnv

direnv Skill

Shell extension for loading and unloading environment variables based on the current directory.

Overview

direnv enables:

• Per-project environment configurations
• Automatic loading of 12-factor app environment variables
• Isolated development environments with language-specific layouts
• Secure allowlist-based security model
• Integration with Nix, asdf, and version managers

Quick Start

Installation

# macOS
brew install direnv

# Linux (Debian/Ubuntu)
sudo apt install direnv

# Linux (binary)
curl -sfL https://direnv.net/install.sh | bash

# Verify
direnv version

Shell Hook Configuration

Zsh (~/.zshrc):

eval "$(direnv hook zsh)"

Bash (~/.bashrc):

eval "$(direnv hook bash)"

Fish (~/.config/fish/config.fish):

direnv hook fish | source

Place hook at end of file, after other shell extensions.

Basic Usage

# Create .envrc
echo 'export MY_VAR=value' > .envrc

# Allow the .envrc (required for security)
direnv allow

# Block an .envrc
direnv deny

# Force reload
direnv reload

# Check status
direnv status

Essential Commands

Standard Library (stdlib)

direnv includes a powerful stdlib. Use these functions instead of raw exports.

PATH Management

# Add to PATH (prepends safely)
PATH_add bin
PATH_add node_modules/.bin
PATH_add scripts

# Add multiple paths
PATH_add bin scripts tools

# Remove from PATH
PATH_rm "*/.git/bin"

Environment File Loading

# Load .env file
dotenv

# Load specific file
dotenv .env.local

# Load if exists (no error if missing)
dotenv_if_exists .env.local

# Load parent .envrc
source_up

# Load specific .envrc
source_env ../.envrc

# Load if exists
source_env_if_exists .envrc.local

Language Layouts

# Python - creates virtualenv in .direnv/
layout python
layout python3
layout python python3.11

# Node.js - adds node_modules/.bin to PATH
layout node

# Ruby - sets GEM_HOME
layout ruby

# Go - configures GOPATH
layout go

# Perl - local::lib
layout perl

# Pipenv
layout pipenv

Nix Integration

# Load nix-shell environment
use nix

# Load Nix flake
use flake

# Specific flake
use flake "nixpkgs#hello"

For better flakes support: nix-direnv

Version Managers

# rbenv
use rbenv

# Node.js (fuzzy matching)
use node 18
use node 18.17.0

# From .nvmrc
use node

Validation

# Require variables
env_vars_required API_KEY DATABASE_URL

# Watch for file changes
watch_file package.json
watch_file config/*.yaml
watch_dir config

# Check git branch
if on_git_branch main; then
  export DEPLOY_ENV=production
fi

# Minimum version
direnv_version 2.32.0

# Strict mode (exit on errors)
strict_env

Recommended .envrc Template

#!/usr/bin/env bash
# .envrc - Project environment configuration

# Enforce direnv version
direnv_version 2.32.0

# Load .env file if exists
dotenv_if_exists

# Load local overrides (not committed)
source_env_if_exists .envrc.local

# Language-specific layout
layout node
# or: layout python3

# Add project paths
PATH_add bin
PATH_add scripts

# Development settings
export NODE_ENV=development
export LOG_LEVEL=debug

# Watch configuration files
watch_file package.json
watch_file .tool-versions

Project Structure Best Practice

my-project/
├── .envrc           # Development environment (committed)
├── .envrc.local     # Local overrides (gitignored)
├── .env             # Environment variables (gitignored)
├── .env.example     # Template for team members (committed)
└── .direnv/         # Cache directory (gitignored)

.gitignore

# Environment files with secrets
.env
.env.local
.envrc.local

# direnv cache
.direnv/

Layered Configuration

Use parent directory inheritance:

# ~/projects/.envrc (global dev settings)
export EDITOR=vim
export PAGER=less

# ~/projects/api/.envrc
source_up  # Inherit from parent
export API_PORT=3000
layout node

# ~/projects/api/feature-x/.envrc
source_up  # Inherit from api
export FEATURE_FLAG=true

Custom Extensions

Create at ~/.config/direnv/direnvrc:

# ~/.config/direnv/direnvrc

# Kubernetes context switcher
use_kubernetes() {
  local context="${1:-default}"
  export KUBECONFIG="${HOME}/.kube/config"
  kubectl config use-context "$context" >/dev/null 2>&1
  log_status "kubernetes context: $context"
}

# AWS profile switcher
use_aws() {
  local profile="${1:-default}"
  export AWS_PROFILE="$profile"
  log_status "aws profile: $profile"
}

# Azure subscription
use_azure() {
  local subscription="$1"
  export AZURE_SUBSCRIPTION="$subscription"
  az account set --subscription "$subscription" >/dev/null 2>&1
  log_status "azure subscription: $subscription"
}

# uv Python layout (modern alternative)
layout_uv() {
  if ! has uv; then
    log_error "uv not found. Install: curl -LsSf https://astral.sh/uv/install.sh | sh"
    return 1
  fi

  VIRTUAL_ENV="$(pwd)/.venv"
  if [[ ! -d "$VIRTUAL_ENV" ]]; then
    uv venv
  fi

  PATH_add "$VIRTUAL_ENV/bin"
  export VIRTUAL_ENV
}

Usage in .envrc:

use kubernetes dev-cluster
use aws production
layout uv

Common Patterns

Python with uv

# .envrc
direnv_version 2.32.0
dotenv_if_exists

# Use uv for Python
if has uv; then
  layout_uv
else
  layout python3
fi

export PYTHONDONTWRITEBYTECODE=1

Node.js Project

# .envrc
direnv_version 2.32.0
dotenv_if_exists
source_env_if_exists .envrc.local

layout node

export NODE_ENV=development
export PORT=3000

watch_file package.json

Kubernetes Development

# .envrc
dotenv_if_exists

use_kubernetes dev-cluster

export KUBECONFIG="${HOME}/.kube/config"
export KUBE_NAMESPACE=my-app

PATH_add bin

Multi-Environment Support

# .envrc
direnv_version 2.32.0

# Determine environment
if on_git_branch main; then
  ENV=production
elif on_git_branch staging; then
  ENV=staging
else
  ENV=development
fi

export APP_ENV="$ENV"

# Load environment-specific config
dotenv_if_exists ".env.$ENV"
source_env_if_exists ".envrc.$ENV"

log_status "environment: $ENV"

Troubleshooting Quick Reference

# Check status
direnv status

# Force reload
direnv reload

# Re-allow .envrc
direnv allow

# Debug environment
direnv dump
direnv show_dump

# Export for debugging
direnv export bash

Common Issues

IDE Integration

VS Code

Install direnv extension.

JetBrains IDEs

Install direnv integration plugin.

Emacs

(use-package envrc
  :hook (after-init . envrc-global-mode))

Vim/Neovim

" Use direnv.vim plugin
Plug 'direnv/direnv.vim'

Security Notes

1. Always review .envrc before allowing - direnv executes arbitrary code
2. Never commit secrets - Use .env files in .gitignore
3. Use .envrc.local for sensitive overrides - Keep local, never commit
4. Trust hierarchy - Parent directories can override child settings

References

• references/installation.md - Complete installation guide
• references/stdlib-functions.md - Full stdlib reference
• references/troubleshooting.md - Extended troubleshooting
• Official docs: https://direnv.net/
• Stdlib reference: https://direnv.net/man/direnv-stdlib.1.html
• nix-direnv: https://github.com/nix-community/nix-direnv