Nixpkgs is the git repository containing all packages and NixOS modules/expressions. Installing packages directly from the master branch of the Nixpkgs repo is possible, but risky, since git commits are merged into master before being heavily tested. That's where channels are useful.
A "channel" is a name for the latest "verified" git commits in Nixpkgs. Each channel has a different definition of what "verified" means. Each time a new git commit is verified, the channel declaring this verification gets updated. Contrary to a user of the git master branch, a channel user will benefit from both verified commits and binary packages from the binary cache.
Channels are reified as git branches in the nixpkgs repository and as disk images in the channels webpage. There is also the handy nix channel status webpage that tracks the age of channels.
There are several channels, each with its own use case and verification phase.
The official channels
Channels can be broadly categorized into stable and unstable channels, and large and small channels:
- Stable channels (
nixos-22.11) provide conservative updates for fixing bugs and security vulnerabilities, but do not receive major updates after initial release. New stable channels are released every six months.
- Unstable channels (
nixpkgs-unstable) correspond to the main development branch (master) of Nixpkgs, delivering the latest tested updates on a rolling basis.
- Stable channels (
- Large channels (
nixos-unstable) provide binary builds for the full breadth of Nixpkgs.
- Small channels (
nixos-unstable-small) are identical to large channels, but contain fewer binaries. This means they update faster, but require more to be built from source.
- Large channels (
Most users will want the stable/large channel, currently
Like packages installed via
nix-env, channels are managed at user-level. NixOS uses the channels set for the
root user to update the system-wide configuration; channels set for other users control only the user environment for that user. 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:
|Listing current channels|
|Adding a primary channel|
|Adding other channels|
|Remove a channel|
|Updating a channel|
|Updating all channels|
Note that updating channels won't cause a rebuild in itself; if you want to update channels and rebuild, you can use
nixos-rebuild with the
--upgrade flag to do both in one step.
Channel update process
The channel update process begins when anyone with commit access pushes changes to either
master or one of the
Then, for each unstable channel (see above), a particular job at hydra.nixos.org is started which must succeed:
- For NixOS: the trunk-combined/tested job, which includes some automated NixOS tests.
- For nixos-small: the unstable-small/tested job.
- For nixpkgs: the trunk/unstable job, which contains some critical release packages.
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.
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.
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.
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.
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.
You can find the channel history at https://channels.nix.gsc.io/
Check build status
$ 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
- NixOS Discourse: Differences between Nix channels - Details about differences between, e.g.,