Nix Hash

Hashes in Nix

Cryptographic hashes play an essential role in a lot of places in the Nix ecosystem. When using a hash somewhere, two criteria are essential to do so properly: the algorithm used and the encoding (and, to some extend, what is hashed).

Supported algorithms are md5, sha1, sha256, sha512. The first two are deprecated and should not be used anymore, but you may still stumble upon them in existing code.

A hash – which is simply a sequence of bytes – is usually encoded in order to be representable as string. Common encodings are base16 (commonly called "hex"), base32 and base64. Note that the base32 is a custom one that is not documented nor standardized in any way! If possible, use the provided hashing tools to convert hashes to it (see below). base32 is used by Nix in a lot of places because it is shorter than hex but can still safely be part of a file path (as it contains no slashes).

Usage

Many derivations are so-called fixed-output derivations, meaning that you need to know and specify the hash of the output in advance. As an example, let's look at fetchurl:

src = fetchurl {
  url = "https://example.org/downloads/source-code.zip";
  sha256 = "1g6ycnji10q5dd0avm6bz4lqpif82ppxjjq4x7vd8xihpgg3dm91";
};

You can specify the hash in any base that's supported. Thus, sha256 = "21d536debb3076d4f6e9044bd9ef15c8c58b29f9cbd4ad406b058310a565debc"; is equally allowed.

An alternative – and supposedly preferred – way of specifying hashes are so-called "SRI hashes". They're pretty simple, you just prepend the algorithm used and a dash to the hash:

src = fetchurl {
  url = "https://example.org/downloads/source-code.zip";
  hash = "sha256-1g6ycnji10q5dd0avm6bz4lqpif82ppxjjq4x7vd8xihpgg3dm91";
};

What exactly is hashed

Some content can either be hashed "flat" or "recursively". "flat" (sometimes also called "file") is simply taking the hash of the file, byte by byte, and will give you the same result as for example `sha256sum -b myfile.zip`. "recursive" (or sometimes "path") hashing takes multiple files, path names and metadata (attributes) into consideration. It works by NARing the input before hashing.

For fetchurl, the option to switch between both is called recursiveHash and defaults to false.

fetchzip on the other hand will download the file, unzip it and then recursively hash the output. There's no option.

Tools

The tool of choice for hashing is nix-hash, although it will be deprecated one day. The new alternatives are Nix_command/hash-file and Nix_command/hash-path, which however are "EXPERIMENTAL and subject to change". nix-hash offers the --to-base32 flag (which the new alternatives don't at the moment) that takes in a hex hash and converts that hash to custom-base32. On the other hand, nix-hash does not support the new sha512 algorithm or the base64 encoding.

When dealing with remote files, nix-prefetch-url offers a handy shortcut for downloading the file into the Nix store and printing out its hash. (nix-prefetch-url --unpack is its fetchzip equivalent.)

Further reading

• Eelco Dolstra's phd thesis, section 5.1.
• Github Issue about which encoding is used where, and what pitfalls can arise from it.