+1
日增长
15,549
stars
947
forks
79
watchers
798
prs
814
issues
66
releases
README
direnv -- unclutter your .profile
=================================
direnv is an extension for your shell. It augments existing shells with a
new feature that can load and unload environment variables depending on the
current directory.
Use cases
Load 12factor apps environment variables
Create per-project isolated development environments
Load secrets for deployment
How it works
Before each prompt, direnv checks for the existence of a .envrc file (and
optionally a .env file) in the current
and parent directories. If the file exists (and is authorized), it is loaded
into a bash sub-shell and all exported variables are then captured by
direnv and then made available to the current shell.
It supports hooks for all the common shells like bash, zsh, tcsh and fish.
This allows project-specific environment variables without cluttering the
~/.profile file.
Because direnv is compiled into a single static executable, it is fast enough
to be unnoticeable on each prompt. It is also language-agnostic and can be
used to build solutions similar to rbenv, pyenv and phpenv.
Getting Started
Prerequisites
Unix-like operating system (macOS, Linux, ...)
A supported shell (bash, zsh, tcsh, fish, elvish, powershell, murex, nushell)
Basic Installation
1. direnv is packaged in most distributions already. See the installation documentation for details.
2. hook direnv into your shell.
Now restart your shell.
Quick demo
To follow along in your shell once direnv is installed.
shell
Create a new folder for demo purposes.
$ mkdir ~/my-project
$ cd ~/my-project
Show that the FOO environment variable is not loaded.
$ echo ${FOO-nope}
nope
Create a new .envrc. This file is bash code that is going to be loaded by
direnv.
$ echo export FOO=foo .envrc
.envrc is not allowed
The security mechanism didn't allow to load the .envrc. Since we trust it,
let's allow its execution.
$ direnv allow .
direnv: reloading
direnv: loading .envrc
direnv export: +FOO
Show that the FOO environment variable is loaded.
$ echo ${FOO-nope}
foo
Exit the project
$ cd ..
direnv: unloading
And now FOO is unset again
$ echo ${FOO-nope}
nope
Some stdlib functions store files in .direnv/. Add .direnv/ to your
.gitignore. For local overrides that you do not commit, put
source_env_if_exists .envrc.local in .envrc and also ignore .envrc.local.
The stdlib
Exporting variables by hand is a bit repetitive so direnv provides a set of
utility functions that are made available in the context of the .envrc file.
As an example, the PATH_add function is used to expand and prepend a path to
the $PATH environment variable. Instead of export PATH=$PWD/bin:$PATH you
can write PATH_add bin. It's shorter and avoids a common mistake where
$PATH=bin.
To find the documentation for all available functions check the
direnv-stdlib(1) man page.
It's also possible to create your own extensions by creating a bash file at
~/.config/direnv/direnvrc or ~/.config/direnv/lib/.sh. This fileTop issues
#68How to turn down verbosity?72 comments · 2013-07-27#73Picking up aliases and functions64 comments · 2013-08-20#129Unload hook49 comments · 2014-06-20#556Load .envrc.local, .envrc.dist41 comments · 2020-01-20#443Support for loading shell completion scripts35 comments · 2019-01-19#440direnv: error .envrc file not found after installing direnv using Snap in zsh34 comments · 2019-01-10#253PATH gets mangled when using direnv from git-bash on Windows31 comments · 2017-02-20#106Interaction with tmux30 comments · 2014-03-05
Discussions
#1652Specifying precmds in `.envrc`0 comments · 2026-10-20#1590ccline: type plain English at zsh when you forget a command — pairs with direnv nicely0 comments · 2026-06-10#1558Automatically add `.gitignore`:`*` into `.direnv` dir1 comments · 2026-03-07#1554Direnv fails to allow in a folder that is not a git repository.1 comments · 2026-02-19#1547Offline mode?1 comments · 2026-01-28#1495direnv errors in git repo1 comments · 2025-09-16#1492Use `direnv exec` as shebang1 comments · 2025-09-08#1474Execute a command on leaving the directory1 comments · 2025-07-25
Latest release
Release v2.38.2 v2.38.2 2026-10-10fix(zsh): load the .envrc in a new shell and on cd from shell functions again (1633, 1634) fix(fish): stop completions from breaking after the first prompt (1635, 1636) fix(pixi): require_allowed for the manifest file as well (1632)