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