direnv

direnv Skill

This skill provides comprehensive guidance for working with direnv, covering installation, configuration, stdlib functions, and best practices for per-project environment management.

When to Use This Skill

Use this skill when:

• Installing and configuring direnv on macOS or Linux
• Creating or modifying .envrc files for projects
• Setting up per-project environment variables
• Configuring language-specific layouts (Python, Node.js, Ruby, Go, Perl)
• Integrating direnv with Nix or Nix Flakes
• Managing secrets and environment configuration for teams
• Troubleshooting environment loading issues
• Creating custom direnv extensions

Core Concepts

What is direnv?

direnv is a shell extension that loads and unloads environment variables based on the current directory. When you cd into a directory with a .envrc file, direnv automatically loads the environment. When you leave, it unloads the changes.

Security Model

direnv uses an allowlist-based security approach:

• New or modified .envrc files must be explicitly allowed with direnv allow
• Prevents automatic execution of untrusted scripts
• Use direnv deny to revoke access

How It Works

1. Shell hook intercepts directory changes
2. Checks for .envrc file in current or parent directories
3. If allowed, executes .envrc in a bash subshell
4. Captures exported variables and applies them to current shell

Installation

macOS (Homebrew - Recommended)

brew install direnv

Linux

# Ubuntu/Debian
sudo apt install direnv

# Fedora
sudo dnf install direnv

# Arch
sudo pacman -S direnv

# Binary installer (any system)
curl -sfL https://direnv.net/install.sh | bash

Verify Installation

direnv version

Shell Configuration

Add the hook to your shell's config file. This is required for direnv to function.

Zsh (~/.zshrc)

eval "$(direnv hook zsh)"

With Oh My Zsh:

plugins=(... direnv)

Bash (~/.bashrc)