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