cachix: a command line client for Nix binary caches

Never build software twice

Cachix is a hosted binary cache for Nix, and this repository holds its command line client, written in Haskell. The pitch in the README is one line: never build software twice.

That problem is specific to Nix and worth explaining, because it decides whether you need this at all. Nix computes a content-addressed store path for every derivation. If two people or two CI jobs build the same derivation, they do the same work twice, and the second build has to fetch the toolchain, the sources and the dependencies all over again. A binary cache is where the finished store path is published once, so the second build downloads a NAR instead of recompiling it.

So the audience is people who run Nix in a team or in CI, where the same dependency is pulled more than once. A single-user workstation that builds things nobody else needs will not notice much difference.

The client is the piece that talks to the hosted service at cachix.org, and the account and cache management live in a web app at app.cachix.org. The command is available on Hackage, and it is also in nixpkgs as pkgs.cachix, which matters for anyone who installs their tooling through Nix, since the client is then a build artefact of the same system it manages caches for.

The repository is not archived, and the last push was on 2026-10-18. There are no GitHub releases for the project, which is unusual and worth knowing if you script around version numbers.

Six command groups, one binary

The help output is the clearest description of the design, since the whole surface fits on one screen. The binary is called cachix, it takes an optional config path with -c or --config, an alternative host with --host or --hostname defaulting to https://cachix.org, a verbose flag and a version flag, and then a single command.

The groups are the structure of the tool.

The config commands are authtoken, which configures an authentication token for Cachix, and config, which manages configuration settings for the client.

The cache commands are generate-keypair, which generates a signing key pair for a binary cache, use, which configures a binary cache in nix.conf, and remove, which takes a binary cache out of nix.conf.

The push commands are push, which uploads Nix store paths to a binary cache, watch-exec, which runs a command while watching /nix/store for newly added store paths and uploads them, and watch-store, which does the same watching without running anything.

The store path command is pin, which pins a store path so it is not garbage collected.

The daemon command is daemon, which runs a daemon that listens to push requests over a unix socket, and the Cachix Deploy command is deploy, which manages remote Nix-based systems. The diagnostic command is doctor, which checks the Cachix configuration and connectivity.

That doctor command deserves attention from anyone evaluating the client, because the failure mode of a cache setup is otherwise confusing. A misconfigured cache usually surfaces as a build that suddenly cannot find a dependency, not as an obvious error at setup time, so a built-in connectivity check is more useful than it looks.

Installing the client with nix-env

The client is installed through Nix, and the documented way to get the current release is a single nix-env invocation pointing at the Cachix install endpoint:

nix-env -iA cachix -f https://cachix.org/api/v1/install

If you already manage packages with nixpkgs, the attribute is pkgs.cachix, which is the path most people will take.

Then you need an account, and the README is explicit that this is a separate step from installing the binary. You create an account at https://app.cachix.org to manage caches, and the help text repeats the same instruction with a login link, which tells you that an unauthenticated client is close to useless.

For development, the project documents installing from master rather than a release, which is the usual shape for a Haskell project published to Hackage and nixpkgs. The classic nix-env form, with the extra substituter and the trusted public key for the Cachix cache already wired in:

nix-env -if https://github.com/cachix/cachix/tarball/master --extra-substituters 'https://cachix.cachix.org' --extra-trusted-public-keys 'cachix.cachix.org-1:eWNHQldwUO7G2VkjpnjDbWwy4KQ/HNxht7H4SSoMckM='

And with Nix 2.4 or later, the flake form is shorter:

nix profile install github:cachix/cachix/latest --accept-flake-config

Note the difference in what these two do. The nix-env form also passes the substituter and the trusted public key, so the cache is immediately usable for fetches. The profile form installs the client only, and the cache still has to be added with the use command or edited into nix.conf by hand.

Pushing store paths without babysitting the build

The push commands are the part that changes how you work, and the difference between them is a matter of who does the waiting.

push uploads store paths to a binary cache. You decide which paths, and the command does the upload. This is the one to use from a CI job at the end of a build, where the set of interesting paths is known.

watch-store watches /nix/store for newly added store paths and uploads them to a binary cache. There is no command to run and no list to assemble: the client notices what the build produced. This suits a long build, a multi-stage derivation chain, or a local experiment where you want the artefacts saved as they appear.

watch-exec is watch-store with a command attached. It runs a command while watching /nix/store for newly added store paths and uploading them, which means the command and the upload are a single unit, and the client can begin uploading without waiting for the command to finish.

That distinction is the interesting one for CI. A build that produces a hundred derivations in sequence can have its outputs uploaded as they are produced rather than at the end, so the cache is useful to the next job almost immediately instead of after the longest stage completes.

Two details apply across the push commands. The upload needs a cache configured, which is what the use command and the authtoken command are for, and the paths being pushed must still exist locally, since the client uploads store paths rather than building them.

The pin command sits alongside these for a related reason. A store path that has been uploaded to a cache can still be garbage collected from a local machine, and pin prevents that, which matters when the local copy is the only one you can rebuild from.

Wiring a cache into nix.conf, and running a local daemon

The cache commands are the configuration side of the client, and they cover the two things you would otherwise edit in nix.conf by hand.

use configures a binary cache in nix.conf, and remove takes a binary cache out of nix.conf again. Between them they cover the whole lifecycle of pointing Nix at a cache, which is a nicer property than editing the substituters list by hand, because a mistake there produces a confusing failure rather than an obvious one.

generate-keypair generates a signing key pair for a binary cache. This is for the case where you run your own cache rather than using the hosted one, and it is also the mechanism behind the daemon.

daemon runs a daemon that listens to push requests over a unix socket. A unix socket is the point: the daemon accepts pushes from local processes over a local socket rather than over the network, so a build on the same machine can hand paths to a long-lived process that does the uploading. The daemon model fits the case where you want uploads to continue after the build command returns, and where a background process holding the authentication and the connection is simpler than reconnecting for every batch.

The import command works in the other direction, bringing the contents of a binary cache from an S3-compatible object storage service into Cachix. It exists for migration, where an organisation already keeps its Nix artefacts in an object store and wants them served through the cache service without a second upload of everything by hand.

The deploy command is the outlier in the list. It manages remote Nix-based systems with Cachix Deploy, which is a different product surface from the local cache commands, and the README keeps it in its own group for that reason.

A Haskell project with its own development environment

The repository layout shows what kind of codebase this is. There are two Haskell components, cachix/ for the command itself and cachix-api/ for the API, each with its own changelog, and the build is driven by Nix files rather than a plain cabal workflow alone: default.nix, flake.nix, genpaths.nix, shell.nix and git-hooks.nix, plus a flake.lock.

The developer setup is unusually complete for a command line tool. There is a devenv.nix for a development environment, a hie.yaml for Haskell IDE Engine configuration, a cabal.project, an .hlint.yaml for the linter, a .envrc for direnv, and a .devcontainer/ directory. The combination means a contributor can get a consistent toolchain with one directory, and an editor that understands the project layout, without assembling that themselves.

The repository also contains a RELEASE.md and a repl directory, and the changelogs are kept in the tree at cachix/CHANGELOG.md for the command and cachix-api/CHANGELOG.md for the API. Since there are no GitHub releases, those files are the release history, which is a good reason to read them before upgrading rather than after something changes.

One caveat on the licensing question. The repository metadata does not state a licence, and the README does not have a licence section either. For a client you install from a package manager that is mostly a non-issue, but if you intend to read the source, vendor it, or redistribute a modified build, confirm the terms first rather than assuming the permissive defaults of the wider Haskell ecosystem.

Support channels are the usual ones: documentation at docs.cachix.org, a Matrix room, a Discord server, and [email protected].

Editorial conclusion

Adopt cachix if you build Nix derivations that other people or other jobs also need, and you want a hosted binary cache with a command line workflow rather than hand-written Nix configuration. Do not adopt it if your builds are unique to one machine, since a cache only pays off when the same path is fetched again, and do not adopt it expecting a documented licence, because the repository metadata does not state one and you should confirm the terms before redistributing the client itself. Before you start, create an account at app.cachix.org, set an auth token with the authtoken command, and use the doctor command to check configuration and connectivity, since a cache that is configured but unreachable fails at build time rather than at push time.

Frequently asked questions

Official sources

1. cachix/cachix on GitHub
2. Issues
3. Project website
4. README