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