pyrox.dev
1# Upgrading NixOS {#sec-upgrading}
2
3The best way to keep your NixOS installation up to date is to use one of
4the NixOS *channels*. A channel is a Nix mechanism for distributing Nix
5expressions and associated binaries. The NixOS channels are updated
6automatically from NixOS's Git repository after certain tests have
7passed and a selection of packages has been built successfully
8(see `nixos/release-combined.nix` and `nixos/release-small.nix`).
9These channels are:
10
11- *Stable channels*, such as [`nixos-25.05`](https://channels.nixos.org/nixos-25.05).
12 These only get conservative bug fixes and package upgrades. For
13 instance, a channel update may cause the Linux kernel on your system
14 to be upgraded from 4.19.34 to 4.19.38 (a minor bug fix), but not
15 from 4.19.x to 4.20.x (a major change that has the potential to break things).
16 Stable channels are generally maintained until the next stable
17 branch is created.
18
19- The *unstable channel*, [`nixos-unstable`](https://channels.nixos.org/nixos-unstable).
20 This corresponds to NixOS's main development branch, and may thus see
21 radical changes between channel updates. It's not recommended for
22 production systems.
23
24- *Small channels*, such as [`nixos-25.05-small`](https://channels.nixos.org/nixos-25.05-small)
25 or [`nixos-unstable-small`](https://channels.nixos.org/nixos-unstable-small).
26 These are identical to the stable and unstable channels described above,
27 except that they contain fewer binary packages. This means they get updated
28 faster than the regular channels (for instance, when a critical security patch
29 is committed to NixOS's source tree), but may require more packages to be
30 built from source than usual. They're mostly intended for server environments
31 and as such contain few GUI applications.
32
33To see what channels are available, go to <https://channels.nixos.org>.
34(Note that the URIs of the various channels redirect to a directory that
35contains the channel's latest version and includes ISO images and
36VirtualBox appliances.) Please note that during the release process,
37channels that are not yet released will be present here as well. See the
38Getting NixOS page <https://nixos.org/download/> to find the newest
39supported stable release.
40
41When you first install NixOS, you're automatically subscribed to the
42NixOS channel that corresponds to your installation source. For
43instance, if you installed from a 25.05 ISO, you will be subscribed to
44the `nixos-25.05` channel. To see which NixOS channel you're subscribed
45to, run the following as root:
46
47```ShellSession
48# nix-channel --list | grep nixos
49nixos https://channels.nixos.org/nixos-unstable
50```
51
52To switch to a different NixOS channel, do
53
54```ShellSession
55# nix-channel --add https://channels.nixos.org/channel-name nixos
56```
57
58(Be sure to include the `nixos` parameter at the end.) For instance, to
59use the NixOS 25.05 stable channel:
60
61```ShellSession
62# nix-channel --add https://channels.nixos.org/nixos-25.05 nixos
63```
64
65If you have a server, you may want to use the "small" channel instead:
66
67```ShellSession
68# nix-channel --add https://channels.nixos.org/nixos-25.05-small nixos
69```
70
71And if you want to live on the bleeding edge:
72
73```ShellSession
74# nix-channel --add https://channels.nixos.org/nixos-unstable nixos
75```
76
77You can then upgrade NixOS to the latest version in your chosen channel
78by running
79
80```ShellSession
81# nixos-rebuild switch --upgrade
82```
83
84which is equivalent to the more verbose `nix-channel --update nixos; nixos-rebuild switch`.
85
86::: {.note}
87Channels are set per user. This means that running `nix-channel --add`
88as a non root user (or without sudo) will not affect
89configuration in `/etc/nixos/configuration.nix`
90:::
91
92::: {.warning}
93It is generally safe to switch back and forth between channels. The only
94exception is that a newer NixOS may also have a newer Nix version, which
95may involve an upgrade of Nix's database schema. This cannot be undone
96easily, so in that case you will not be able to go back to your original
97channel.
98:::
99
100## Automatic Upgrades {#sec-upgrading-automatic}
101
102You can keep a NixOS system up-to-date automatically by adding the
103following to `configuration.nix`:
104
105```nix
106{
107 system.autoUpgrade.enable = true;
108 system.autoUpgrade.allowReboot = true;
109}
110```
111
112This enables a periodically executed systemd service named
113`nixos-upgrade.service`. If the `allowReboot` option is `false`, it runs
114`nixos-rebuild switch --upgrade` to upgrade NixOS to the latest version
115in the current channel. (To see when the service runs, see `systemctl list-timers`.)
116If `allowReboot` is `true`, then the system will automatically reboot if
117the new generation contains a different kernel, initrd or kernel
118modules. You can also specify a channel explicitly, e.g.
119
120```nix
121{ system.autoUpgrade.channel = "https://channels.nixos.org/nixos-25.05"; }
122```