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 --use-remote-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.

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.