Channel branches: Difference between revisions

(3 intermediate revisions by 3 users not shown)

Line 1:

Nix channels provide a structured and reliable way to access ~~tested, verified~~ package collections and [[NixOS]] configurations from the [[Nixpkgs]] repository. ~~Rather than installing packages or building systems~~ directly ~~from~~ the frequently updated <code>master</code> branch of Nixpkgs, which receives new commits before extensive testing~~. Because of this~~, ~~users typically follow 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 <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 branch is a curated, tested snapshot of Nixpkgs~~, made available via [https://channels.nixos.org channels.nixos.org]~~. These branches only advance after builds and tests for a given commit have successfully passed on the [[Hydra]] continuous integration system.

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].

Line 10:

Line 8:

* 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.

** '''Stable channels''' (e.g. <code>nixos-25.11</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.

** '''Large channels''' (e.g. <code>nixos-25.11</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.

** '''Small channels''' (e.g. <code>nixos-25.11-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.

Line 30:

Line 28:

|-

| Adding a primary channel

|<code><nowiki>nix-channel --add https://nixos.org~~/channels~~/channel-name nixos</nowiki></code>

|<code><nowiki>nix-channel --add https://channels.nixos.org/channel-name nixos</nowiki></code>

|-

| Adding other channels

Line 54:

Line 52:

== 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.

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.11</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:

Line 61:

Line 59:

{

inputs = {

nixpkgs.url = "github:nixos/nixpkgs/nixos-25.05";

nixpkgs.url = "github:nixos/nixpkgs/nixos-25.11";

nixpkgs-unstable.url = "github:nixos/nixpkgs/nixos-unstable";

};

Line 78:

Line 76:

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

* For NixOS: the [http://hydra.nixos.org/job/nixos/~~trunk-combined~~/tested ~~trunk-combined~~/tested] job, which includes some automated NixOS tests.

* For NixOS: the [http://hydra.nixos.org/job/nixos/unstable/tested nixos/unstable/tested] job, which includes some automated NixOS tests.

* For nixos-small: the [http://hydra.nixos.org/job/nixos/unstable-small/tested unstable-small/tested] job.

* For nixos-small: the [http://hydra.nixos.org/job/nixos/unstable-small/tested nixos/unstable-small/tested] job.

* For nixpkgs: the [http://hydra.nixos.org/job/nixpkgs/~~trunk~~/unstable ~~trunk~~/unstable] job, which contains some critical release packages.

* For nixpkgs: the [http://hydra.nixos.org/job/nixpkgs/unstable/unstable nixpkgs/unstable/unstable] job, which contains some critical release packages.

=== Success Conditions ===

@@ Line 1: / Line 1: @@
-Nix channels provide a structured and reliable way to access tested, verified package collections and [[NixOS]] configurations from the [[Nixpkgs]] repository. Rather than installing packages or building systems directly from the frequently updated <code>master</code> branch of Nixpkgs, which receives new commits before extensive testing. Because of this, users typically follow 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 <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 branch is a curated, tested snapshot of Nixpkgs, made available via [https://channels.nixos.org channels.nixos.org]. These branches only advance after builds and tests for a given commit have successfully passed on the [[Hydra]] continuous integration system.
 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].
@@ Line 10: / Line 8: @@
 * 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.
+** '''Stable channels''' (e.g. <code>nixos-25.11</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.
+** '''Large channels''' (e.g. <code>nixos-25.11</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.
+** '''Small channels''' (e.g. <code>nixos-25.11-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.
@@ Line 30: / Line 28: @@
 |-
 | Adding a primary channel
-|<code><nowiki>nix-channel --add https://nixos.org/channels/channel-name nixos</nowiki></code>
+|<code><nowiki>nix-channel --add https://channels.nixos.org/channel-name nixos</nowiki></code>
 |-
 | Adding other channels
@@ Line 54: / Line 52: @@
 == 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.
+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.11</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:
@@ Line 61: / Line 59: @@
 {
    inputs = {
-     nixpkgs.url = "github:nixos/nixpkgs/nixos-25.05";
+     nixpkgs.url = "github:nixos/nixpkgs/nixos-25.11";
      nixpkgs-unstable.url = "github:nixos/nixpkgs/nixos-unstable";
    };
@@ Line 78: / Line 76: @@
 Then, for each '''unstable''' channel (see above), a particular job at [https://hydra.nixos.org hydra.nixos.org] is started which must succeed:
-* For NixOS: the [http://hydra.nixos.org/job/nixos/trunk-combined/tested trunk-combined/tested] job, which includes some automated NixOS tests.
+* For NixOS: the [http://hydra.nixos.org/job/nixos/unstable/tested nixos/unstable/tested] job, which includes some automated NixOS tests.
-*  For nixos-small: the [http://hydra.nixos.org/job/nixos/unstable-small/tested unstable-small/tested] job.
+*  For nixos-small: the [http://hydra.nixos.org/job/nixos/unstable-small/tested nixos/unstable-small/tested] job.
-*  For nixpkgs: the [http://hydra.nixos.org/job/nixpkgs/trunk/unstable trunk/unstable] job, which contains some critical release packages.
+*  For nixpkgs: the [http://hydra.nixos.org/job/nixpkgs/unstable/unstable nixpkgs/unstable/unstable] job, which contains some critical release packages.
 === Success Conditions ===