direnv -- unclutter your .profile

direnv is an extension for your shell. It augments existing shells with anew feature that can load and unload environment variables depending on thecurrent 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 in thecurrent and parent directories. If the file exists (and is authorized), it isloaded into a bash sub-shell and all exported variables are then capturedby 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 enoughto be unnoticeable on each prompt. It is also language-agnostic and can beused 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)

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.

# 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

The stdlib

Exporting variables by hand is a bit repetitive so direnv provides a set ofutility 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 tothe $PATH environment variable. Instead of export PATH=$PWD/bin:$PATH youcan write PATH_add bin. It's shorter and avoids a common mistake where$PATH=bin.

To find the documentation for all available functions check thedirenv-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 isloaded before your .envrc and thus allows you to make your own extensions todirenv.

Docs

• Install direnv
• Hook into your shell
• Develop for direnv
• Manage your rubies with direnv and ruby-install
• Community Wiki

Make sure to take a look at the wiki! It contains all sorts of usefulinformation such as common recipes, editor integration, tips-and-tricks.

Man pages

• direnv(1) man page
• direnv-stdlib(1) man page
• direnv.toml(1) man page

FAQ

Based on GitHub issues interactions, here are the top things that have beenconfusing for users:

1. direnv has a standard library of functions, a collection of utilities thatI found useful to have and accumulated over the years. You can find ithere: https://github.com/direnv/direnv/blob/master/stdlib.sh

2. It's possible to override the stdlib with your own set of function byadding a bash file to ~/.config/direnv/direnvrc. This file is loaded andit's content made available to any .envrc file.

3. direnv is not loading the .envrc into the current shell. It's creating anew bash sub-process to load the stdlib, direnvrc and .envrc, and onlyexports the environment diff back to the original shell. This allows direnvto record the environment changes accurately and also work with all sortsof shells. It also means that aliases and functions are not exportableright now.

Contributing

Bug reports, contributions and forks are welcome. All bugs or other forms ofdiscussion happen on http://github.com/direnv/direnv/issues .

Or drop by on Matrix tohave a chat. If you ask a question make sure to stay around as not everyone isactive all day.

Complementary projects

Here is a list of projects you might want to look into if you are using direnv.

• starship - A cross-shell prompt.
• Projects for Nix integration - choose from one of a variety of projects offering improvements over Direnv's built-in use_nix implementation.

Related projects

Here is a list of other projects found in the same design space. Feel free tosubmit new ones.

• Environment Modules - one of the oldest (in a good way) environment-loading systems
• autoenv - lightweight; doesn't support unloads
• zsh-autoenv - a feature-rich mixture of autoenv and smartcd: enter/leave events, nesting, stashing (Zsh-only).
• asdf - a pure bash solution that has a plugin system. The asdf-direnv plugin allows using asdf managed tools with direnv.
• ondir - OnDir is a small program to automate tasks specific to certain directories
• shadowenv - uses an s-expression format to define environment changes that should be executed

COPYRIGHT

MIT licence - Copyright (C) 2019 @zimbatm and contributors