Direnv

Direnv is an automatic environment setup utility, loading the specified project environment automatically when you enter your project directory, and reporting the loaded variables to you.

After installing direnv from Nixpkgs using your preferred method of installation, you can set up the .envrc file at the root of your directory. Refer to the Direnv Wiki for some examples. For Nix projects, you will probably want to use the special use_nix keyword, that automatically loads the shell.nix file for your repository.

At the root of your repository, Direnv can start by allowing the recently-created .envrc file to execute:

$ direnv allow .
direnv: loading .envrc
direnv: using nix
[...]
 +SIZE +SOURCE_DATE_EPOCH +STRINGS +STRIP +TEMP +TEMPDIR +TMP +TMPDIR +_PATH +buildInputs +builder +checkPhase +cmakeFlags +configureFlags +doCheck +enableParallelBuilding +name +nativeBuildInputs +out +postCheck +preCheck +preConfigure +propagatedBuildInputs +propagatedNativeBuildInputs +shell +src +stdenv +system +testInputs +version ~PATH

🛡︎︎

Security information: Direnv will never run an unknown .envrc file unless explicitly authorised. As these files run arbitrary code in your computer, it is a good idea to review the .envrc files from remote repositories before running direnv allow.

Once Direnv detects that the current working directory is no longer inside the repository with a .envrc file, it will automatically unload the environment:

$ cd ..
direnv: unloading

State

Direnv stores files in $XDG_DATA_HOME/direnv. It contains the information required to persist all allowed and denied .envrc files across the filesystem.

Keeping that directory means that an .envrc file only needs to be allowed once in order to run automatically.

nix-direnv & lorri

While Direnv has full support for Nix development environments, third-party developers have improved upon Direnv's default implementation of the special use_nix keyword, resulting in the development of nix-direnv and lorri.

Configuring on NixOS

There is a NixOS Module for Direnv (and nix-direnv) which automatically sets everything up in a given NixOS machine. The following line of code is everything that's necessary for NixOS to automatically install and hook Direnv to the available shells in the system:

❄︎ configuration.nix

{
  programs.direnv.enable = true;
}

🟆︎

Tip: In order to affect your NixOS system by your nix-language-specific changes you must first evaluate it:

$ nixos-rebuild switch --sudo

For a full list of Direnv module options, see programs.direnv.

The NixOS module uses nix-direnv by default when Direnv is enabled. This behavior can be overridden by setting the programs.direnv.nix-direnv.enable option.

User Customization & Repositories

Direnv is meant to be used as a personalized environment file so each user can set any necessary environment variables and/or run some setup scripts. As every user can have different environment needs (such as changing ports, location of $TMPDIR, project-specific VCS/PGP/SSH credentials) it’s recommended not to track or commit the .envrc so users may make adjustments for themselves. In fact, it’s best to add both to your ignorefile

.direnv
.envrc

to avoid accidentally checking in your personal setup (as seen in Nixpkgs’s repository). If you have a complex .envrc you wish to share, create a .envrc.example file that users can copy, symlink, or source depending on what works for them.

Troubleshooting

Hooking Shells

Depending on the shell you are using, you need to add a line in your shell configuration file. See the Hook section of the Direnv Documentation for more information.

Setting Direnv up using the NixOS module should do this by default.

See Also

• direnv.net.
• The Direnv Wiki.