README.md
1direnv -- unclutter your .profile
2=================================
3
4[](https://builtwithnix.org)
5[](https://repology.org/project/direnv/versions)
6[](https://repology.org/project/direnv/versions)
7
8`direnv` is an extension for your shell. It augments existing shells with a
9new feature that can load and unload environment variables depending on the
10current directory.
11
12## Use cases
13
14* Load 12factor apps environment variables
15* Create per-project isolated development environments
16* Load secrets for deployment
17
18## How it works
19
20Before each prompt, direnv checks for the existence of a `.envrc` file in the
21current and parent directories. If the file exists (and is authorized), it is
22loaded into a **bash** sub-shell and all exported variables are then captured
23by direnv and then made available to the current shell.
24
25It supports hooks for all the common shells like bash, zsh, tcsh and fish.
26This allows project-specific environment variables without cluttering the
27`~/.profile` file.
28
29Because direnv is compiled into a single static executable, it is fast enough
30to be unnoticeable on each prompt. It is also language-agnostic and can be
31used to build solutions similar to rbenv, pyenv and phpenv.
32
33## Getting Started
34
35### Prerequisites
36
37* Unix-like operating system (macOS, Linux, ...)
38* A supported shell (bash, zsh, tcsh, fish, elvish)
39
40### Basic Installation
41
421. direnv is packaged in most distributions already. See [the installation documentation](docs/installation.md) for details.
432. [hook direnv into your shell](docs/hook.md).
44
45Now restart your shell.
46
47### Quick demo
48
49To follow along in your shell once direnv is installed.
50
51```
52# Create a new folder for demo purposes.
53$ mkdir ~/my-project
54$ cd ~/my-project
55
56# Show that the FOO environment variable is not loaded.
57$ echo ${FOO-nope}
58nope
59
60# Create a new .envrc. This file is bash code that is going to be loaded by
61# direnv.
62$ echo export FOO=foo > .envrc
63.envrc is not allowed
64
65# The security mechanism didn't allow to load the .envrc. Since we trust it,
66# let's allow its execution.
67$ direnv allow .
68direnv: reloading
69direnv: loading .envrc
70direnv export: +FOO
71
72# Show that the FOO environment variable is loaded.
73$ echo ${FOO-nope}
74foo
75
76# Exit the project
77$ cd ..
78direnv: unloading
79
80# And now FOO is unset again
81$ echo ${FOO-nope}
82nope
83```
84
85### The stdlib
86
87Exporting variables by hand is a bit repetitive so direnv provides a set of
88utility functions that are made available in the context of the `.envrc` file.
89
90As an example, the `PATH_add` function is used to expand and prepend a path to
91the $PATH environment variable. Instead of `export PATH=$PWD/bin:$PATH` you
92can write `PATH_add bin`. It's shorter and avoids a common mistake where
93`$PATH=bin`.
94
95To find the documentation for all available functions check the
96[direnv-stdlib(1) man page](man/direnv-stdlib.1.md).
97
98It's also possible to create your own extensions by creating a bash file at
99`~/.config/direnv/direnvrc` or `~/.config/direnv/lib/*.sh`. This file is
100loaded before your `.envrc` and thus allows you to make your own extensions to
101direnv.
102
103## Docs
104
105* [Install direnv](docs/installation.md)
106* [Hook into your shell](docs/hook.md)
107* [Develop for direnv](docs/development.md)
108* [Manage your rubies with direnv and ruby-install](docs/ruby.md)
109* [Community Wiki](https://github.com/direnv/direnv/wiki)
110
111Make sure to take a look at the wiki! It contains all sorts of useful
112information such as common recipes, editor integration, tips-and-tricks.
113
114### Man pages
115
116* [direnv(1) man page](man/direnv.1.md)
117* [direnv-stdlib(1) man page](man/direnv-stdlib.1.md)
118* [direnv.toml(1) man page](man/direnv.toml.1.md)
119
120### FAQ
121
122Based on GitHub issues interactions, here are the top things that have been
123confusing for users:
124
1251. direnv has a standard library of functions, a collection of utilities that
126 I found useful to have and accumulated over the years. You can find it
127 here: https://github.com/direnv/direnv/blob/master/stdlib.sh
128
1292. It's possible to override the stdlib with your own set of function by
130 adding a bash file to `~/.config/direnv/direnvrc`. This file is loaded and
131 it's content made available to any `.envrc` file.
132
1333. direnv is not loading the `.envrc` into the current shell. It's creating a
134 new bash sub-process to load the stdlib, direnvrc and `.envrc`, and only
135 exports the environment diff back to the original shell. This allows direnv
136 to record the environment changes accurately and also work with all sorts
137 of shells. It also means that aliases and functions are not exportable
138 right now.
139
140## Contributing
141
142Bug reports, contributions and forks are welcome. All bugs or other forms of
143discussion happen on http://github.com/direnv/direnv/issues .
144
145Or drop by on [IRC (#direnv on freenode)](irc://irc.freenode.net/#direnv) to
146have a chat. If you ask a question make sure to stay around as not everyone is
147active all day.
148
149## Complementary projects
150
151Here is a list of projects you might want to look into if you are using direnv.
152
153* [starship](https://starship.rs/) - A cross-shell prompt.
154* [nix-direnv](https://github.com/nix-community/nix-direnv) - A fast, persistent use_nix implementation for direnv.
155
156## Related projects
157
158Here is a list of other projects found in the same design space. Feel free to
159submit new ones.
160
161* [Environment Modules](http://modules.sourceforge.net/) - one of the oldest (in a good way) environment-loading systems
162* [autoenv](https://github.com/kennethreitz/autoenv) - lightweight; doesn't support unloads
163* [zsh-autoenv](https://github.com/Tarrasch/zsh-autoenv) - a feature-rich mixture of autoenv and [smartcd](https://github.com/cxreg/smartcd): enter/leave events, nesting, stashing (Zsh-only).
164* [asdf](https://github.com/asdf-vm/asdf) - a pure bash solution that has a plugin system. The [asdf-direnv](https://github.com/asdf-community/asdf-direnv) plugin allows using asdf managed tools with direnv.
165* [ondir](https://github.com/alecthomas/ondir) - OnDir is a small program to automate tasks specific to certain directories
166* [shadowenv](https://shopify.github.io/shadowenv/) - uses an s-expression format to define environment changes that should be executed
167
168## COPYRIGHT
169
170[MIT licence](LICENSE) - Copyright (C) 2019 @zimbatm and [contributors](https://github.com/direnv/direnv/graphs/contributors)
171
){kind=link}
){kind=link}
){kind=link}