colemickens / nix-direnv

A fast, persistent use_nix/use_flake implementation for direnv [maintainer=@Mic92 / @bbenne10]

nix-direnv

A faster, persistent implementation of direnv's use_nix and use_flake, to replace the built-in one.

Prominent features:

• significantly faster after the first run by caching the nix-shell environment
• prevents garbage collection of build dependencies by symlinking the resulting shell derivation in the user's gcroots (Life is too short to lose your project's build cache if you are on a flight with no internet connection)

Why not use lorri instead?

Compared to lorri, nix-direnv is simpler (and requires no external daemon) and supports flakes. Additionally, lorri can sometimes re-evaluate the entirety of nixpkgs on every change (leading to perpetual high CPU load).

Installation

Heads up: nix-direnv requires a modern Bash and GNU Grep. MacOS ships with outdated or non-GNU versions of these tools, As a work-around we suggest that macOS users install direnv/grep via Nix or Homebrew. Discussion of these problems can be found here.

There are different ways to install nix-direnv, pick your favourite:

Via home-manager (Recommended)

Via home-manager

Note that while the home-manager integration is recommended, some use cases require the use of features only present in some versions of nix-direnv. It is much harder to control the version of nix-direnv installedwith this method. If you require such specific control, please use another method of installing nix-direnv.

In $HOME/.config/nixpkgs/home.nix add

{
  # ...other config, other config...

  programs = {
    direnv = {
      enable = true;
      enableBashIntegration = true; # see note on other shells below
      nix-direnv.enable = true;
    };

    bash.enable = true; # see note on other shells below
  };
}

Check the current Home Manager Options for integration with shells other than Bash. Be sure to also allow home-manager to manage your shell with programs.<your_shell>.enable = true.

Direnv's source_url

Direnv source_url

Put the following lines in your .envrc:

if ! has nix_direnv_version || ! nix_direnv_version 2.3.0; then
  source_url "https://raw.githubusercontent.com/nix-community/nix-direnv/2.3.0/direnvrc" "sha256-Dmd+j63L84wuzgyjITIfSxSD57Tx7v51DMxVZOsiUD8="
fi

Via system configuration on NixOS

Via system configuration on NixOS

For NixOS 23.05+ all that's required is

{
  programs.direnv.enable = true;
}

other available options are:

{ pkgs, ... }: {
  #set to default values
  programs.direnv = {
    package = pkgs.direnv;
    silent = false;
    loadInNixShell = true;
    direnvrcExtra = "";
    nix-direnv = {
      enable = true;
      package = pkgs.nix-direnv;
    };
  }

With `nix-env`

With nix-env

As non-root user do the following:

nix-env -f '<nixpkgs>' -iA nix-direnv

Then add nix-direnv to $HOME/.config/direnv/direnvrc:

source $HOME/.nix-profile/share/nix-direnv/direnvrc

With `nix profile`

With nix profile

As non-root user do the following:

nix profile install nixpkgs#nix-direnv

Then add nix-direnv to $HOME/.config/direnv/direnvrc:

source $HOME/.nix-profile/share/nix-direnv/direnvrc

From source

From source

Clone the repository to some directory and then source the direnvrc from this repository in your own ~/.config/direnv/direnvrc:

# put this in ~/.config/direnv/direnvrc
source $HOME/nix-direnv/direnvrc

Usage example

Either add shell.nix or a default.nix to the project directory:

# save this as shell.nix
{ pkgs ? import <nixpkgs> {}}:

pkgs.mkShell {
  packages = [ pkgs.hello ];
}

Then add the line use nix to your envrc:

$ echo "use nix" >> .envrc
$ direnv allow

If you haven't used direnv before, make sure to hook it into your shell first.

Using a non-standard file name

You may use a different file name than shell.nix or default.nix by passing the file name in .envrc, e.g.:

$ echo "use nix foo.nix" >> .envrc

Flakes support

nix-direnv also comes with an alternative use_flake implementation. The code is tested and does work but the upstream flake api is not finalized, so we we cannot guarantee stability after an nix upgrade.

Like use_nix, our use_flake will prevent garbage collection of downloaded packages, including flake inputs.

Creating a new flake-native project

This repository ships with a flake template. which provides a basic flake with devShell integration and a basic .envrc.

To make use of this template, you may issue the following command:

$ nix flake new -t github:nix-community/nix-direnv <desired output path>

Integrating with a existing flake

$ echo "use flake" >> .envrc && direnv allow

The use flake line also takes an additional arbitrary flake parameter, so you can point at external flakes as follows:

use flake ~/myflakes#project

Advanced usage

use flake

Under the covers, use_flake calls nix print-dev-env. The first argument to the use_flake function is the flake expression to use, and all other arguments are proxied along to the call to print-dev-env. You may make use of this fact for some more arcane invocations.

For instance, if you have a flake that needs to be called impurely under some conditions, you may wish to pass --impure to the print-dev-env invocation so that the environment of the calling shell is passed in.

You can do that as follows:

$ echo "use flake . --impure" > .envrc
$ direnv allow

use nix

Like use flake, use nix now uses nix print-dev-env. Due to historical reasons, the argument parsing emulates nix shell.

This leads to some limitations in what we can reasonably parse.

Currently, all single-word arguments and some well-known double arguments will be interpeted or passed along.

Manual reload of the nix environment

To avoid delays and time consuming rebuilds at unexpected times, you can use nix-direnv in the "manual reload" mode. nix-direnv will then tell you when the nix environment is no longer up to date. You can then decide yourself when you want to reload the nix environment.

To activate manual mode, use nix_direnv_manual_reload in your .envrc like this:

nix_direnv_manual_reload
use nix # or use flake

To reload your nix environment, use the nix-direnv-reload command:

$ nix-direnv-reload

Known arguments

• -p: Starts a list of packages to install; consumes all remaining arguments
• --include / -I: Add the following path to the list of lookup locations for <...> file names
• --attr / -A: Specify the output attribute to utilize

--command, --run, --exclude, --pure, -i, and --keep are explicitly ignored.

All single word arguments (-j4, --impure etc) are passed to the underlying nix invocation.

Tracked files

nix-direnv makes a performance tradeoff and only considers changes in a limited number of files when deciding to update its cache.

• for use nix this is:

  • ~/.direnvrc
  • ~/.config/direnv/direnvrc
  • .envrc,
  • A single nix file. In order of preference:
    • The file argument to use nix
    • default.nix if it exists
    • shell.nix if it exists

• for use flake this is:

  • ~/.direnvrc
  • ~/.config/direnv/direnvrc
  • .envrc
  • flake.nix
  • flake.lock
  • devshell.toml if it exists

To add more files to be checked use nix_direnv_watch_file like this

nix_direnv_watch_file your-file.nix
use nix # or use flake

Or - if you don't mind the overhead (runtime and conceptual) of watching all nix-files:

nix_direnv_watch_file $(find . -name "*.nix" -printf '"%p" ')

Note that this will re-execute direnv for any nix change, regardless of whether that change is meaningful for the devShell in use.

nix_direnv_watch_file must be invoked before either use flake or use nix to take effect.

General direnv tips

• Changing where direnv stores its cache
• Quickly setting up direnv in a new nix project

Other projects in the field

• lorri
• sorri
• nixify
• lorelei