Configure Nix to use a custom binary cache

Nix can be configured to use a binary cache with the substituters and trusted-public-keys settings, either exclusively or in addition to cache.nixos.org.

Tip

Follow the tutorial to set up an HTTP binary cache and create a key pair for signing store objects.

Warning

Nix will accept any requested store object signed with private keys corresponding to the configured public keys. Access to those private keys thus allows substituting arbitrary files into your Nix store. This includes executables that may run with elevated privileges or automatically!

Only add public keys you trust unconditionally.

For example, given a binary cache at https://example.org with public key My56...Q==%, and some derivation in default.nix, make Nix exclusively use that cache once by passing settings as command line flags:

$ nix-build --substituters https://example.org --trusted-public-keys example.org:My56...Q==%

To permanently configure trying the custom cache before the public cache, add it as extra-substiters with lower priority value to the Nix configuration file:

$ echo "extra-substituters = https://example.org?priority=30" >> /etc/nix/nix.conf
$ echo "extra-trusted-public-keys = example.org:My56...Q==%" >> /etc/nix/nix.conf

To always use only the custom cache:

$ echo "substituters = https://example.org" >> /etc/nix/nix.conf
$ echo "trusted-public-keys = example.org:My56...Q==%" >> /etc/nix/nix.conf

NixOS

On NixOS, Nix is configured through the nix.settings option:

{ ... }: {
  nix.settings = {
    substituters = [ "https://example.org?priority=30" ];
    trusted-public-keys = [ "example.org:My56...Q==%" ];
  };
}

Tip

Use remote build machines as preferred binary caches to reduce your external traffic.