Apply an environment at a directory boundary
direnv evaluates an approved .envrc when you enter a directory and reverses that environment delta when you leave. It is a convenient bridge to a project's chosen runtime manager and non-secret configuration; it is not a dependency manager, a secret store, or a rollback system for external side effects.
Install the shell hook
brew install direnv
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc
exec zsh
direnv statusThe hook recalculates the environment after directory changes. Use direnv status to confirm which file and approval state the current shell sees.
Review before you allow
cat .envrc
git diff -- .envrc .gitignore
direnv allowallow means that you reviewed shell code and consent to execute it. Re-read the diff after a branch switch, pull, or any edit. A single PATH_add line can change which executable every later command selects.
Keep the connection contract explicit
PATH_add ./bin
source_env_if_exists .envrc.local
use mise
export APP_ENV=developmentA shared .envrc may contain reviewed, non-secret project configuration. Keep tokens and passwords in a credential store or an ignored, permission-restricted local file such as .envrc.local. Commit the shared contract and ignore the local secret file. If a team deliberately keeps the whole .envrc local, ignore it and commit a reviewed .envrc.example that contains variable names and validation instructions, never real secrets.
Know what unload can reverse
direnv can restore shell variables after you leave. It cannot undo files created, processes started, deployments performed, or remote state changed while evaluating .envrc. Keep the file fast and repeatable, and put state-changing operations in separate commands.
Approval is an ongoing review contract
After approval, inspect direnv status, type -a, and printenv to verify the actual result. Use direnv deny to withdraw an approval, and require a fresh review before allowing changed content again. Familiarity with a repository is not approval of a new diff.