Channel branches: Difference between revisions
wording and formatting |
m Reword the first two paragraphs |
||
(14 intermediate revisions by 9 users not shown) | |||
Line 1: | Line 1: | ||
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]. | |||
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]. | |||
== The official channels == | |||
There are several | 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]. | ||
* 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. | |||
* 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. | |||
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 (<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 | == 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. | |||
== | == 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]. | ||
= | === Check build status === | ||
== 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:// | * [[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]] |