Declarative and reproducible developer environments

In the {ref}ad-hoc-envs tutorial, we looked at imperatively creating shell environments using nix-shell -p, for when we need a quick way to access some tools without having to install them globally. We also saw how to execute that command with a specific nixpkgs git commit as an argument, to recreate the same environment used previously.

In this tutorial, we'll see how to declaratively create {term}reproducible shell environments using a configuration file called a Nix expression.

When are declarative shell environments useful?

Both methods of creating development shell environments allow you to provide CLI tools like psql, jq, and tmux, as well as developer libraries like zlib and openssl. However, only the declarative approach allows you to

automatically set shell environment variables,
execute bash commands during environment activation, and
share the exact same environment with other developers.

In addition to these, declaring development environments in Nix expression files enables you to use all the source code workflows you're used to, like committing that file to version control, using code analysis tools, and so on.

Getting started

At the top-level of your project create shell.nix with the following contents:

{ pkgs ? import (fetchTarball "https://github.com/NixOS/nixpkgs/archive/06278c77b5d162e62df170fec307e83f1812d94b.tar.gz") {} }:

pkgs.mkShell {
  buildInputs = [
    pkgs.which
    pkgs.htop
    pkgs.zlib
  ];
}

:::{note} To understand the first line, read our tutorial on {ref}pinning Nixpkgs. :::

We import nixpkgs and make a shell with which and htop available in $PATH. We use zlib to provide libraries and headers in case we're compiling something against it.

To enter the environment:

$ nix-shell
these paths will be fetched (0.07 MiB download, 0.20 MiB unpacked):
  /nix/store/072a6x7rwv5f8wr6f5s1rq8nnm767cfp-htop-2.2.0
copying path '/nix/store/072a6x7rwv5f8wr6f5s1rq8nnm767cfp-htop-2.2.0' from 'https://cache.nixos.org'...

[nix-shell:~]$

This command will start downloading the missing packages from the https://cache.nixos.org binary cache.

Once the download is done, you are dropped into a new shell. This shell provides the packages specified in shell.nix.

Run htop to confirm that it is present. Quit the program by hitting q.

Now try which htop to check where the htop command is on disk. You should see something similar to this:

[nix-shell:~]$ which htop
/nix/store/y3w2i8kfdbfj9rx287ad52rahjpgv423-htop-2.2.0/bin/htop

Customizing your developer environment

Given the following shell.nix:

{ pkgs ? import (fetchTarball "https://github.com/NixOS/nixpkgs/archive/06278c77b5d162e62df170fec307e83f1812d94b.tar.gz") {} }:

pkgs.mkShell {
  buildInputs = [
    pkgs.which
    pkgs.htop
    pkgs.zlib
  ];

  shellHook = ''
    echo hello
  '';

  MY_ENVIRONMENT_VARIABLE = "world";
}

Running nix-shell we observe:

$ nix-shell
hello

[nix-shell:~]$ echo $MY_ENVIRONMENT_VARIABLE
world

The shellHook section allows you to execute bash while entering the shell environment.
Any attributes passed to mkShell function are available once the shell environment is active.

`direnv`: Automatically activating the environment on directory change

Besides activating the environment for each project, every time you change shell.nix you need to re-enter the shell.

You can use direnv to automate this process for you, with the downside that each developer needs to install it globally.

Setting up `direnv`

At the top-level of your project run:

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

The next time you launch your terminal and enter the top-level of your project, direnv will check for changes.

$ cd myproject
direnv: loading myproject/.envrc
direnv: using nix
hello

Next steps

Take a look at our {ref}pinning Nixpkgs tutorial to see different ways to import Nixpkgs.
To quickly set up a Nix project, read Getting started Nix template.

4.4 KiB Raw Blame History