2020-06-09 07:59:20 -04:00
.. _pinning-nixpkgs:
2020-06-09 07:53:00 -04:00
2020-06-09 07:49:45 -04:00
Towards reproducibility: Pinning nixpkgs
2020-06-05 07:48:24 -04:00
========================================
2020-06-19 11:30:46 -04:00
In various Nix examples, you'll often see references to `<nixpkgs> <https://github.com/NixOS/nixpkgs> `_ , as follows.
2020-06-05 07:48:24 -04:00
.. code :: nix
{ pkgs ? import <nixpkgs> {}
}:
...
2020-06-19 11:30:46 -04:00
This is **convenient** to quickly demonstrate a Nix expression and get it working by importing Nix packages.
2020-06-05 07:48:24 -04:00
2020-06-19 11:30:46 -04:00
However, the resulting Nix expression **is not fully reproducible** . The `` <nixpkgs> `` reference
2020-06-21 08:26:51 -04:00
is set from the **local** `` $NIX_PATH `` environment variable. In most cases, this is set at the time Nix is installed
2020-06-19 11:30:46 -04:00
to the `` nixpkgs-unstable `` channel, and therefore it is likely to differ from machine to machine.
2020-06-05 07:48:24 -04:00
.. note ::
2020-06-19 11:30:46 -04:00
`Channels <https://nixos.wiki/wiki/Nix_channels> `_ are a way of distributing Nix software, but they are being phased out.
2020-06-21 08:26:51 -04:00
Even though they are still used by default, it is recommended to avoid channels
2020-06-05 07:48:24 -04:00
and `` <nixpkgs> `` by always setting `` NIX_PATH= `` to be empty.
2020-06-19 11:30:46 -04:00
Pinning packages with URLs inside a Nix expression
--------------------------------------------------
2020-06-05 07:48:24 -04:00
2020-06-19 11:30:46 -04:00
To create **fully reproducible** Nix expressions, we can pin an exact versions of nixpkgs.
2020-06-05 07:48:24 -04:00
2020-06-19 11:30:46 -04:00
The simplest way to do this is to fetch the required nixpkgs version as a tarball specified via the relevant git commit hash:
2020-06-05 07:48:24 -04:00
.. code :: nix
{ pkgs ? import (fetchTarball https://github.com/NixOS/nixpkgs/archive/3590f02e7d5760e52072c1a729ee2250b5560746.tar.gz) {};
}:
...
2020-06-19 11:30:46 -04:00
Picking the commit can be done via `status.nixos.org <https://status.nixos.org/> `_ ,
which lists all the releases and the latest commit that has passed all tests.
2020-06-05 07:48:24 -04:00
2020-06-19 11:30:46 -04:00
When choosing a commit, it is recommended to follow either
2020-06-05 07:48:24 -04:00
2020-06-19 11:30:46 -04:00
* the **latest stable NixOS** release by using a specific version, such as `` nixos-20.03 `` , **or**
* the latest **unstable release** via `` nixos-unstable `` .
2020-06-05 07:48:24 -04:00
Dependency management with niv
------------------------------
2020-06-19 11:30:46 -04:00
If you'd like a bit more automation around bumping dependencies, including nixpkgs,
2020-06-21 08:26:51 -04:00
`niv <https://github.com/nmattia/niv/> `_ is made for exactly that. Niv itself is available
2020-06-19 11:30:46 -04:00
in `` nixpkgs `` so using it is simple::
2020-06-05 07:48:24 -04:00
2020-06-09 07:59:20 -04:00
$ nix-shell -p niv --run "niv init"
2020-06-05 07:48:24 -04:00
2020-06-19 11:30:46 -04:00
This command will generate `` nix/sources.json `` with information about how and where
dependencies are fetched. It will also create `` nix/sources.nix `` which glues the sources together in Nix.
2020-06-05 07:48:24 -04:00
2020-06-19 11:30:46 -04:00
By default `` niv `` will use the **latest stable** NixOS release. However, you should check to see which version is currently specified in `the niv repository <https://github.com/nmattia/niv> `_ if you require a specific release, as it might lag behind.
2020-06-05 07:48:24 -04:00
2020-06-19 11:30:46 -04:00
You can use the generated `` sources.nix `` file as follows:
2020-06-05 07:48:24 -04:00
.. code :: nix
2020-06-21 08:26:51 -04:00
{ sources ? import ./sources.nix
2020-06-05 07:48:24 -04:00
, pkgs ? import sources.nixpkgs {}
2020-06-21 08:26:51 -04:00
}:
2020-06-05 07:48:24 -04:00
...
2020-06-19 11:30:46 -04:00
And you can update all the dependencies by running::
2020-06-09 07:59:20 -04:00
$ nix-shell -p niv --run "niv update"
2020-06-05 07:48:24 -04:00
2020-06-11 10:15:35 -04:00
Going Forward
-------------
2020-06-19 11:30:46 -04:00
For more examples and details of the different ways to pin `` nixpkgs `` , see :ref: `ref-pinning-nixpkgs` .
2020-06-11 10:15:35 -04:00