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.
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.
Now restart your shell.
To follow along in your shell once direnv is installed.
# 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
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 file is
loaded before your .envrc
and thus allows you to make your own extensions to
direnv.
Note that this functionality is not supported in .env
files. If the
coexistence of both is needed, one can use .envrc
for leveraging stdlib and
append dotenv
at the end of it to instruct direnv to also read the .env
file next.
Make sure to take a look at the wiki! It contains all sorts of useful information such as common recipes, editor integration, tips-and-tricks.
Based on GitHub issues interactions, here are the top things that have been confusing for users:
direnv has a standard library of functions, a collection of utilities that I found useful to have and accumulated over the years. You can find it here: https://github.com/direnv/direnv/blob/master/stdlib.sh
It’s possible to override the stdlib with your own set of function by
adding a bash file to ~/.config/direnv/direnvrc
. This file is loaded and
its content made available to any .envrc
file.
direnv is not loading the .envrc
into the current shell. It’s creating a
new bash sub-process to load the stdlib, direnvrc and .envrc
, and only
exports the environment diff back to the original shell. This allows direnv
to record the environment changes accurately and also work with all sorts
of shells. It also means that aliases and functions are not exportable
right now.
Bug reports, contributions and forks are welcome. All bugs or other forms of discussion happen on http://github.com/direnv/direnv/issues .
Or drop by on Matrix to have a chat. If you ask a question make sure to stay around as not everyone is active all day.
To run our tests, use these commands: (you may need to install homebrew)
brew bundle
make test
Here is a list of projects you might want to look into if you are using direnv.
use_nix
implementation.Here is a list of other projects found in the same design space. Feel free to submit new ones.
.envrc
files that does not hook into your shell and favors speed over convenience.Looking for help or customization?
Get in touch with Numtide to get a quote. We make it easy for companies to work with Open Source projects: https://numtide.com/contact
MIT licence - Copyright (C) 2019 @zimbatm and contributors