ScriptsApr 14, 2026·3 min read

direnv — Automatic Environment Switcher for Your Shell

direnv loads and unloads environment variables when you cd into a directory. Per-project PATH, API keys, and language versions — applied automatically when you enter, cleaned up when you leave. The foundation of reproducible dev environments.

Script Depot
Script Depot · Community
TL;DR
direnv auto-loads per-project environment variables when you enter a directory.
§01

What it is

direnv is a shell extension that loads and unloads environment variables when you cd into a directory. You create an .envrc file in your project root, and direnv automatically sets PATH, API keys, language versions, and any other environment variables when you enter that directory. When you leave, it cleans everything up.

direnv targets developers working on multiple projects that each need different environment configurations. Instead of remembering to source scripts or switch version managers, direnv handles it transparently.

§02

Why it saves time or tokens

Manually managing environment variables across projects leads to 'works on my machine' bugs and forgotten configuration steps. direnv makes environments self-documenting and automatic. The .envrc file serves as both documentation and execution. For onboarding new developers or AI agents to a project, a well-configured .envrc means the environment is correct the moment you enter the directory.

§03

How to use

  1. Install direnv: brew install direnv (macOS) or your OS package manager
  2. Hook direnv into your shell: add eval "$(direnv hook zsh)" to your .zshrc
  3. Create an .envrc file in your project and run direnv allow to trust it
§04

Example

# .envrc
export DATABASE_URL='postgres://localhost:5432/myapp'
export API_KEY='dev-key-12345'
export NODE_ENV='development'

# Use a specific Node version via nvm
use node 20

# Add local bin to PATH
PATH_add bin

# Load from .env file
dotenv
FeatureDescription
Auto-loadVariables set on directory entry
Auto-unloadVariables removed on directory exit
SecurityRequires explicit direnv allow
.env supportLoad existing .env files
Language supportbash, zsh, fish, tcsh, elvish
§05

Related on TokRepo

§06

Common pitfalls

  • Forgetting to run direnv allow after editing .envrc means changes do not take effect; direnv blocks untrusted changes as a security measure
  • Committing .envrc with real secrets exposes them in version control; use .envrc for non-sensitive config and reference a .env file (gitignored) for secrets
  • Some shell integrations conflict with other version managers (nvm, pyenv); check the direnv wiki for compatibility notes

Frequently Asked Questions

Is direnv secure?+

direnv requires you to explicitly run direnv allow for each .envrc file before it executes. If the file changes, you must re-allow it. This prevents malicious .envrc files from executing automatically. The allow list is stored in a local database, not in the repository.

Does direnv work with .env files?+

Yes. Use the dotenv command in your .envrc to load variables from a .env file. This lets you keep secrets in a gitignored .env file while using direnv for automatic loading. The .envrc itself can be committed safely because it just references the .env file.

Can direnv manage language versions?+

Yes. direnv supports use commands for several language version managers. 'use node 20' activates Node 20 via nvm, 'use python 3.11' activates Python via pyenv, and similar commands exist for Go, Ruby, and other languages. This replaces manual version switching.

Does direnv work in CI/CD pipelines?+

direnv can work in CI, but most CI systems use their own environment variable mechanisms. If your CI runs shell scripts that cd into directories, direnv hooks work normally. However, many teams prefer to set CI environment variables through the CI platform's native configuration.

How does direnv compare to dotenv?+

dotenv libraries load .env files at application runtime within a specific language (Node.js, Python). direnv loads environment variables at the shell level before your application starts, making them available to any tool or language. direnv is language-agnostic and works for all commands you run in that directory.

Citations (3)
  • direnv GitHub— direnv loads and unloads environment variables based on directory
  • direnv Docs— direnv configuration and shell hooks
  • 12 Factor App— Environment variable best practices for development
Related on TokRepo
AI coding toolsDevOps toolsFeatured workflows

Discussion

Sign in to join the discussion.
No comments yet. Be the first to share your thoughts.

Related Assets

NAPI-RS — Build Node.js Native Addons in Rust

Write high-performance Node.js native modules in Rust with automatic TypeScript type generation and cross-platform prebuilt binaries.

Script Depot

Mamba — Fast Cross-Platform Package Manager

A drop-in conda replacement written in C++ that resolves environments in seconds instead of minutes.

Script Depot

Plasmo — The Browser Extension Framework

Build, test, and publish browser extensions for Chrome, Firefox, and Edge using React or Vue with hot-reload and automatic manifest generation.

Script Depot
◈Home🔍Search👤Me