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