Channel branches

Nix channels provide a structured and reliable way to access package collections and NixOS configurations from the Nixpkgs repository. Unlike directly accessing the frequently updated master branch of Nixpkgs which receives new commits before extensive testing, a channel branch is a curated, tested snapshot of Nixpkgs. These branches only advance after builds and tests for a given commit have successfully passed on the Hydra continuous integration system and are made available via channels.nixos.org.

Each channel branch follows a corresponding development branch to which new commits are first added. These new commits are then "verified" using the Hydra continuous integration system, where each channel branch corresponds to building any new or updated packages for that branch and perform the associated tests. A channel branch is updated once its builds succeeds for a new commit. Contrary to users of the development branches, channel branch users will benefit from both "verified" commits and pre-built packages from the official public binary cache.

The official channels

There are several types of channel branches, each with its own use case and verification phase. Channels can be broadly categorized into stable and unstable channels, and large and small channels. To view the current official channels, see the channel status webpage.

• Stable vs unstable:
  • Stable channels (e.g. nixos-26.05) only provide conservative updates for fixing bugs and security vulnerabilities, but do not receive major updates after the initial release. New stable channels are released every six months.
  • Unstable channels (e.g. nixos-unstable, nixpkgs-unstable) follow the master branch of Nixpkgs, delivering the latest tested updates on a rolling basis.

• Large vs small:
  • Large channels (e.g. nixos-26.05, nixos-unstable) are updated only after Hydra has finished building the full breadth of Nixpkgs.
  • Small channels (e.g. nixos-26.05-small, nixos-unstable-small) are identical to large channels, but are updated as soon as Hydra has finished building a defined set of commonly-used packages. Thus, users following these channels will get faster updates but may need to build any packages they use from outside the defined set themselves. These channels are intended to be used for server setups, for example.

For most users, a stable/large channel is recommended.

The nix-channel command

Nix channels are maintained separately for each user account, including the root user. Each user, including root, has their own list of subscribed channels and local copies of those channel definitions. In NixOS, the channels configured for root control system-level operations such as nixos-rebuild, while channels for other users only affect their personal environments and package installations through tools like nix-env or nix-shell. If you wish to change the channel used by the system-level configuration (/etc/nixos/configuration.nix), ensure you run the correct nix-channel command as root:

Common nix-channel commands

Listing current channels	nix-channel --list
Adding a primary channel	nix-channel --add https://channels.nixos.org/channel-name nixos
Adding other channels	nix-channel --add https://some.channel/url my-alias
Remove a channel	nix-channel --remove channel-alias
Updating a channel	nix-channel --update channel-alias
Updating all channels	nix-channel --update
Rollback the last update (useful if the last update breaks the nixos-rebuild)	nix-channel --rollback

Channel usage in NixOS

Note that updating channels won't cause a rebuild in itself; if you want to update channels and rebuild, you can run nixos-rebuild --upgrade switch to do both in one step. See Updating NixOS for more in-depth information on changing/updating channels in NixOS.

Using channel branches with flakes

Although Flakes do not make use of traditional Nix channels, they can still reference the same channel branches by specifying them in the flake’s inputs. These branches, such as nixos-26.05 or nixos-unstable, correspond to named references within the Nixpkgs repository and serve a similar role in selecting which version of Nixpkgs or other inputs to use.

A simple example of defining channel branches in a flake:

❄︎ flake.nix

{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-26.05";
    nixpkgs-unstable.url = "github:nixos/nixpkgs/nixos-unstable";
  };
  ...
}

In this way, flakes offer fine-grained, declarative control over which versions of inputs are used, while no longer depending on the global Nix channel system.

Internal channel update process

This section details the inner workings of how channels get generated from the Nixpkgs repository into channel branches. The channel update process begins when anyone with commit access pushes changes to either master or one of the release-XX.XX branches.

Hydra Build

Then, for each unstable channel (see above), a particular job at hydra.nixos.org is started which must succeed:

• For NixOS: the nixos/unstable/tested job, which includes some automated NixOS tests.
• For nixos-small: the nixos/unstable-small/tested job.
• For nixpkgs: the nixpkgs/unstable/unstable job, which contains some critical release packages.

Success Conditions

For a channel update to succeed, two conditions need to be satisfied:

• Particular jobset evaluation needs to be completely built ie. no more queued jobs, even if some jobs may fail
• Particular jobset evaluation's tested/unstable job needs to be built succesfully

The nixos.org server has a cronjob for which nixos-channel-scripts are executed and poll for the newest jobset that satisfies the above two conditions and trigger a channel update.

Channel Update

Once the job succeeds at a particular nixpkgs commit, cache.nixos.org will download binaries from hydra.nixos.org. When the download completes, the channel updates.

For the NixOS channel command-not-found index is generated, which can take some time since it has to fetch all packages. nixpkgs is quickly updated since none of the above needs to happen once a channel update is triggered.

The resulting channel artifacts (nixexprs.tar.zstd, ISO images, command-not-found index, etc.) are then available on releases.nixos.org. The exact URL depends on the channel branch (see #Channel Versioning for more info on full_version):

Channel name	URL template
nixpkgs-unstable	/nixpkgs/nixpkgs-{full_version}/{artifact}
nixpkgs-*-darwin	/nixpkgs/{major}.{minor}-darwin/nixpkgs-darwin-{full_version}/{artifact}
nixos-unstable	/nixos/unstable/nixos-{full_version}/{artifact}
nixos-unstable-small	/nixos/unstable-small/nixos-{full_version}/{artifact}
nixos-*	/nixos/{major}.{minor}/nixos-{full_version}/{artifact}
nixos-*-small	/nixos/{major}.{minor}-small/nixos-{full_version}/{artifact}

channels.nixos.org/{channel_name} will redirect to the most recent release's directory of artifacts (example).

Updates for the -unstable channels typically take a few days after commits land in the master branch.

To find out when a channel was last updated, check https://status.nixos.org/. The progress of a particular pull request can be tracked via the (third-party) Nixpkgs Pull Request Tracker.

Channel Versioning

Each successful run of this process corresponds to a specific version of that channel. The version format differs slightly based on the channel:

• nixpkgs-unstable, nixos-unstable, nixos-unstable-small, and nixpkgs-*-darwin use the format XX.YYpreN.C, where:
  • XX.YY is the major-minor version: for unstable channels, this is the yet-unreleased version (e.g. if the latest stable version is 26.11, then this would be 27.05); for darwin channels, this is the corresponding version (e.g. 26.05 for nixpkgs-26.05-darwin).
  • C is an abbreviation of the nixpkgs commit that was used by Hydra to build this release: this can be found in the "Input" tab of the Hydra job (example), and should only contain the first 12 characters of the hash (except for versions older than 22.05, check the exhaustive list of artifacts for those).
  • N is the number of commits between C and the nixpkgs repo's root commit.

• nixos-* uses a similar format, XX.YY.N.C, but where N has a slightly different meaning: in this case, it should be the number of commit between master and the merge base between master and C.

For example, nixpkgs-unstable's version 26.11pre1081052.f45c6f04c2f0 is an unstable version released while the latest stable version was 26.05 (which means the next version was 26.11), and it was based on commit f45c6f04c2f0, which is the 1081052nd commit of the repo. (For completeness's sake, it corresponds to Hydra job 1829602, if you're curious.)

Computing the channel version

If you have already downloaded that channel, you can evaluating lib.version (e.g. with nix-instantiate /path/to/nixpkgs -A lib.version --eval) to find the exact channel version it corresponds to, which can be used to manually fetch it from releases.nixos.org if needed later.

If you don't already have a download of the exact channel version you want, you can still try to determine it yourself using a git checkout of the nixpkgs repo. For this, you will need to start from a specific commit that was used by a Hydra job. If you already have a commit but don't know if it corresponds to a Hydra job, you will probably need to try and manually find a close commit in the listing of the corresponding jobset. Once you have that commit you can determine the N of the version string:

Find the value of N for a given commit C depending on the channel

Channel name	Command
nixpkgs-unstable, nixos-unstable, nixpkgs-unstable-small, nixpkgs-*-darwin	git rev-list $C | wc -l
nixos-*, nixos-*-small	git rev-list $(git merge-base master $C)..$C | wc -l

Once you have gathered all this information, you can use it to form the version string using the earlier information.

For example, if you want to find the nixos-26.05 version that corresponds to commit 7fc6f2c20af0 (Hydra job 1829619), you would compute N using git rev-list $(git merge-base master 7fc6f2c20af0)..7fc6f2c20af0 | wc -l, which would give you a value of N = 10882, allowing you to determine that its exact version string is 26.05.10882.7fc6f2c20af0 (and indeed, its artifact page does prove we're right!).

Check build status

hydra-check

$ hydra-check --channel unstable bash
Build Status for nixpkgs.bash.x86_64-linux on unstable
✔ bash-4.4-p23 from 2021-05-23 - https://hydra.nixos.org/build/143785213

also useful for finding build logs

Tips and tricks

When unstable lags behind master

As https://status.nixos.org shows, a downside of nixos-unstable is that when the channel is blocked due to hydra failures, other (security) fixes will also not get in. While of course we try to keep hydra green, it is expected that this happens every once in a while. When you want to upgrade or downgrade a single package while leaving the rest of your system on nixos-unstable, you could use this approach.

See also

• Updating NixOS - For changing branches in NixOS
• Binary Cache
• nix.dev FAQ: Which channel branch should I use?
• It's not about “Flakes vs. Channels” by samueldr