Guide · Open source

How to use direnv: per-folder environment variables explained

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

direnv is an extension for your shell that loads and unloads environment variables based on the directory you are in. This guide explains how it works, how to set up a .envrc file, and how to use the built-in helper functions. By the end you will be able to keep project-specific settings out of your ~/.profile.

direnvdirenv/direnv · ★ 15.5k · MIT Install options & downloads

Quick start

1Check prerequisites. Confirm you use a Unix-like system and a supported shell such as bash, zsh, tcsh, fish, elvish, powershell, murex or nushell.
2Install direnv. Install direnv using your package manager, following docs/installation.md in the repository.
3Hook direnv into your shell. Follow docs/hook.md to add the hook to your shell configuration, then restart the shell.
4Create a project folder. Make a folder for your project and change into it.
5Write an .envrc file. Add export statements or stdlib calls such as PATH_add bin to a file named .envrc.
6Authorize the file. Run direnv allow . in the folder so direnv loads the .envrc file.
7Ignore generated files. Add .direnv/ to .gitignore and keep local overrides in .envrc.local, which you also ignore.

What direnv does and how it works

Before each prompt, direnv checks for a .envrc file (and optionally a .env file) in the current and parent directories. If the file exists and is authorized, it is loaded and its exported variables are made available to your current shell.

direnv does not load the file into your shell directly. It runs a new bash sub-process to load the stdlib, direnvrc and .envrc, then exports only the environment changes back to your shell. Because direnv is compiled into a single static executable, the README says it is fast enough to be unnoticeable on each prompt.

Check that your system and shell are supported

direnv requires a Unix-like operating system such as macOS or Linux. The README lists these supported shells: bash, zsh, tcsh, fish, elvish, powershell, murex and nushell.

Windows-native users are not a good fit, because the Unix-like system is listed as a prerequisite.

Unix-like operating system (macOS, Linux, ...)
A supported shell (bash, zsh, tcsh, fish, elvish, powershell, murex, nushell)

Install direnv and hook it into your shell

direnv is packaged in most distributions already. The README points to the installation documentation at docs/installation.md for details. After installing, hook direnv into your shell using the instructions in docs/hook.md, then restart your shell.

The README does not list specific install commands, so use the instructions in the linked docs or your package manager.

Create and allow your first .envrc file

Create a project folder and move into it. Then write your variables into a file named .envrc. This file is bash code that direnv loads.

direnv will refuse to load a new .envrc until you authorize it. Run direnv allow in the folder to trust the file. When you leave the folder, direnv unloads the variables again.

Run the commands in your project folder, not your home directory.
Run direnv allow . after every change to .envrc, since the file must be authorized.

$ mkdir ~/my-project
$ cd ~/my-project
$ echo export FOO=foo > .envrc
$ direnv allow .
$ echo ${FOO-nope}
foo
$ cd ..
$ echo ${FOO-nope}
nope

Use the stdlib helper functions

Exporting variables by hand is repetitive, so direnv provides utility functions you can call inside .envrc. For example, PATH_add expands and prepends a path to $PATH. Instead of export PATH=$PWD/bin:$PATH you can write PATH_add bin, which is shorter and avoids a common mistake where $PATH is set to bin.

The full list of functions is in the direnv-stdlib(1) man page, and the stdlib source is in stdlib.sh in the repository.

PATH_add bin

Add your own functions with direnvrc and keep local overrides out of git

You can create your own extensions as a bash file at ~/.config/direnv/direnvrc or as files matching ~/.config/direnv/lib/*.sh. These load before your .envrc, so your functions are available inside it.

Some stdlib functions store files in .direnv/. Add .direnv/ to your .gitignore. For local overrides you do not commit, add source_env_if_exists .envrc.local to .envrc and ignore .envrc.local in git.

The README notes that .env files do not support direnvrc functionality. To use both, keep stdlib calls in .envrc and append dotenv at the end to make direnv also read the .env file.

source_env_if_exists .envrc.local

What people use it for

Load 12factor app environment variables for a project folder
Create per-project isolated development environments
Load secrets for deployment without putting them in ~/.profile
Add project bin directories to PATH with PATH_add
Build version-manager style tooling similar to rbenv, pyenv and phpenv, as the README suggests

Frequently asked questions

Is direnv free to use?

direnv is released under the MIT licence, according to the README. The licence file is in the repository as LICENSE.

What operating systems does direnv support?

The README lists a Unix-like operating system such as macOS or Linux as a prerequisite. Windows-native users are not the target audience.

Which shells work with direnv?

direnv provides hooks for bash, zsh, tcsh and fish. The prerequisites also list elvish, powershell, murex and nushell as supported shells.

Why does direnv say my .envrc is not allowed?

direnv blocks new or changed .envrc files until you trust them. Review the file, then run direnv allow in that folder.

Can I use aliases or shell functions in .envrc?

No. The README says aliases and functions are not exportable, because direnv runs .envrc in a separate bash sub-process and only exports environment changes back.

What are the alternatives to direnv?

The README lists autoenv, shadowenv, mise and quickenv as comparable projects. Quickenv does not hook into your shell and favors speed over convenience, while mise combines direnv, make and asdf in one tool.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

direnv suits developers on Unix-like systems who switch between projects with different environment variables or need to load secrets per folder. It is a poor fit for Windows-native users, people who depend on aliases or shell functions inside the project, or non-technical users who do not want to edit shell hooks. Consider mise or shadowenv if you want a single tool or a different config format.

Install options & downloads