direnv

Installing and Configuring direnv for Shell

# macOS
brew install direnv

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

Add hook to shell config:

# ~/.bashrc
eval "$(direnv hook bash)"

# ~/.zshrc
eval "$(direnv hook zsh)"

Enabling Syntax Highlighting in .envrc Files

Add a shebang to enable syntax highlighting in editors:

#!/usr/bin/env bash

Loading Environment Variables with direnv

Create .envrc in project directory:

# Load from .env file
dotenv

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

# Or set variables directly
export DATABASE_URL="postgresql://user:password@localhost:5432/database"
export API_KEY="secret"

Allow direnv to load the file:

direnv allow

Variables are automatically loaded when entering the directory and unloaded when leaving.

Using direnv with uv Virtual Environments

With uv, there’s no need to activate virtual environments. Use uv run to execute commands within the virtual environment:

uv run python main.py
uv run pytest

See the uv manual for creating and managing virtual environments.

Using direnv with pipenv Virtual Environments

Prefer uv over pipenv. Only use pipenv when automatic activation provides substantial development experience improvements.

# .envrc
export PIPENV_VENV_IN_PROJECT=1
layout pipenv

PIPENV_VENV_IN_PROJECT creates .venv in project directory instead of ~/.local/share/virtualenvs/.

Validating Required Environment Variables

Use env_vars_required to ensure variables are set before proceeding:

# .envrc
env_vars_required CLUSTER_NAME AWS_PROFILE

Logs an error and returns non-zero if any variable is missing or empty. Fails fast at directory entry rather than mid-execution. See env_vars_required in stdlib.

References

• direnv Documentation
• direnv stdlib