Channel branches: Difference between revisions

wording and formatting
Lukec (talk | contribs)
m Reword the first two paragraphs
 
(14 intermediate revisions by 9 users not shown)
Line 1: Line 1:
Nixpkgs is the Git repository containing all package reciptes and NixOS module declarations. Installing packages directly from the <code>master</code> branch of the Nixpkgs repository is possible but risky, since Git commits are merged into <code>master</code> before being heavily tested. That's where channel branches are useful.
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 <code>master</code> 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 [https://channels.nixos.org channels.nixos.org].


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.
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 [https://cache.nixos.org official public binary cache].


Channels are reified as git branches in the [https://github.com/nixos/nixpkgs nixpkgs] repository and as disk images in the [https://nixos.org/channels/ channels webpage]. There is also the handy [https://status.nixos.org/ nix channel status webpage] that tracks the age of channels.
== The official channels ==


There are several channels, each with its own use case and verification phase.
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 [https://status.nixos.org channel status webpage].


== The official channels ==
* Stable vs unstable:
** '''Stable channels''' (e.g. <code>nixos-25.05</code>) 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. <code>nixos-unstable</code>, <code>nixpkgs-unstable</code>) follow the <code>master</code> branch of Nixpkgs, delivering the latest tested updates on a rolling basis.


Channels can be broadly categorized into ''stable'' and ''unstable'' channels, and ''large'' and ''small'' channels:
* Large vs small:
** '''Large channels''' (e.g. <code>nixos-25.05</code>, <code>nixos-unstable</code>) are updated only after Hydra has finished building the full breadth of Nixpkgs.
** '''Small channels''' (e.g. <code>nixos-25.05-small</code>, <code>nixos-unstable-small</code>) 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.


* Stable/unstable:
For most users, a stable/large channel is recommended.
** Stable channels (<code>nixos-23.11</code>) 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 (<code>nixos-unstable</code>, <code>nixpkgs-unstable</code>) correspond to the main development branch (unstable) of Nixpkgs, delivering the latest tested updates on a rolling basis.


* Large/small:
== The nix-channel command ==
** Large channels (<code>nixos-23.11</code>, <code>nixos-unstable</code>) provide binary builds for the full breadth of Nixpkgs.
** Small channels (<code>nixos-23.11-small</code>, <code>nixos-unstable-small</code>) are identical to large channels, but contain fewer binaries. This means they update faster, but require more to be built from source.


Most users will want the stable/large channel, currently <code>nixos-23.11</code>.
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 (<code>/etc/nixos/configuration.nix</code>), ensure you run the correct <code>nix-channel</code> command as root:
 
Like packages installed via <code>nix-env</code>, channels are managed at user-level. NixOS uses the channels set for the <code>root</code> 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 (<code>/etc/nixos/configuration.nix</code>), ensure you run the correct <code>nix-channel</code> command as root:


{| class="wikitable"
{| class="wikitable"
Line 43: Line 41:
| Updating all channels
| Updating all channels
|<code>nix-channel --update</code>
|<code>nix-channel --update</code>
|-
| Rollback the last update (useful if the last update breaks the <code>nixos-rebuild</code>)
|<code>nix-channel --rollback</code>
|}
|}


Note that updating channels won't cause a rebuild in itself; if you want to update channels and rebuild, you can use <code>nixos-rebuild</code> with the <code>--upgrade</code> flag to do both in one step.
== 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 <code>nixos-rebuild --upgrade switch</code> 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 <code>nixos-25.05</code> or <code>nixos-unstable</code>, 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:
 
{{file|flake.nix|nix|<nowiki>
{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-25.05";
    nixpkgs-unstable.url = "github:nixos/nixpkgs/nixos-unstable";
  };
  ...
}
</nowiki>}}
 
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.


== Channel update process ==
== Internal channel update process ==


The channel update process begins when anyone with commit access pushes changes to either <code>master</code> or one of the <code>release-XX.XX</code> branches.
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 <code>master</code> or one of the <code>release-XX.XX</code> branches.


=== Hydra Build ===
=== Hydra Build ===
Line 66: Line 87:
* Particular jobset evaluation's tested/unstable job needs to be built succesfully
* 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.
The nixos.org server has a cronjob for which [https://github.com/nixOS/nixos-channel-scripts nixos-channel-scripts] are executed and poll for the newest jobset that satisfies the above two conditions and trigger a channel update.


=== Channel Update ===
=== Channel Update ===
Line 78: Line 99:
To find out when a channel was last updated, check [https://status.nixos.org/ https://status.nixos.org/]. The progress of a particular pull request can be tracked via the (third-party) [https://nixpk.gs/pr-tracker.html Nixpkgs Pull Request Tracker].
To find out when a channel was last updated, check [https://status.nixos.org/ https://status.nixos.org/]. The progress of a particular pull request can be tracked via the (third-party) [https://nixpk.gs/pr-tracker.html Nixpkgs Pull Request Tracker].


== When unstable lags behind master ==
=== Check build status ===
 
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 [[User:Raboof#using_a_fork_of_a_packaged_project|this approach]].
 
== Channel history ==
 
You can find the channel history at https://channels.nix.gsc.io/
 
== Check build status ==
[https://github.com/nix-community/hydra-check hydra-check]
[https://github.com/nix-community/hydra-check hydra-check]
<syntaxhighlight lang="sh">
<syntaxhighlight lang="sh">
Line 94: Line 107:
</syntaxhighlight>
</syntaxhighlight>
also useful for finding build logs
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 [[User:Raboof#using_a_fork_of_a_packaged_project|this approach]].


== See also ==
== See also ==


* [https://discourse.nixos.org/t/differences-between-nix-channels/13998 NixOS Discourse: Differences between Nix channels] - Details about differences between, e.g., <code>nixos-23.11</code>, <code>nixos-unstable</code>, <code>nixpkgs-unstable</code>, and <code>nixos-*-small</code> channels.
* [[Updating NixOS]] - For changing branches in NixOS
 
* [[Binary Cache]]
* [https://nix.dev/concepts/faq#which-channel-branch-should-i-use nix.dev] FAQ: Which channel branch should I use?
* [https://samuel.dionne-riel.com/blog/2024/05/07/its-not-flakes-vs-channels.html It's not about “Flakes vs. Channels”] by samueldr


[[Category:Nix]]
[[Category:Nix]]
[[Category:NixOS]]
[[Category:Hydra]]
[[Category:Software]]
[[Category:Software]]