nixos/doc/manual/from_md/installation/upgrading.chapter.xml

   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-22.05"><literal>nixos-22.11</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-22.05-small"><literal>nixos-22.11-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 22.11 ISO, you will be subscribed
  64     to the <literal>nixos-22.11</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
  69 nixos 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 22.11 stable channel:
  80   </para>
  81   <programlisting>
  82 # nix-channel --add https://nixos.org/channels/nixos-22.11 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-22.11-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">
 132 system.autoUpgrade.enable = true;
 133 system.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">
 149 system.autoUpgrade.channel = https://nixos.org/channels/nixos-22.11;
 150 </programlisting>
 151   </section>
 152 </chapter>