nixos/doc/manual/installation/upgrading.chapter.md

   1 # Upgrading NixOS {#sec-upgrading}
   2
   3 The best way to keep your NixOS installation up to date is to use one of
   4 the NixOS *channels*. A channel is a Nix mechanism for distributing Nix
   5 expressions and associated binaries. The NixOS channels are updated
   6 automatically from NixOS's Git repository after certain tests have
   7 passed and all packages have been built. These channels are:
   8
   9 -   *Stable channels*, such as [`nixos-22.11`](https://nixos.org/channels/nixos-22.05).
  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.05-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
  31 To 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
  33 contains the channel's latest version and includes ISO images and
  34 VirtualBox appliances.) Please note that during the release process,
  35 channels that are not yet released will be present here as well. See the
  36 Getting NixOS page <https://nixos.org/nixos/download.html> to find the
  37 newest supported stable release.
  38
  39 When you first install NixOS, you're automatically subscribed to the
  40 NixOS channel that corresponds to your installation source. For
  41 instance, if you installed from a 22.11 ISO, you will be subscribed to
  42 the `nixos-22.11` channel. To see which NixOS channel you're subscribed
  43 to, run the following as root:
  44
  45 ```ShellSession
  46 # nix-channel --list | grep nixos
  47 nixos https://nixos.org/channels/nixos-unstable
  48 ```
  49
  50 To 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
  57 use the NixOS 22.11 stable channel:
  58
  59 ```ShellSession
  60 # nix-channel --add https://nixos.org/channels/nixos-22.11 nixos
  61 ```
  62
  63 If 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
  69 And 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
  75 You can then upgrade NixOS to the latest version in your chosen channel
  76 by running
  77
  78 ```ShellSession
  79 # nixos-rebuild switch --upgrade
  80 ```
  81
  82 which is equivalent to the more verbose `nix-channel --update nixos; nixos-rebuild switch`.
  83
  84 ::: {.note}
  85 Channels are set per user. This means that running `nix-channel --add`
  86 as a non root user (or without sudo) will not affect
  87 configuration in `/etc/nixos/configuration.nix`
  88 :::
  89
  90 ::: {.warning}
  91 It is generally safe to switch back and forth between channels. The only
  92 exception is that a newer NixOS may also have a newer Nix version, which
  93 may involve an upgrade of Nix's database schema. This cannot be undone
  94 easily, so in that case you will not be able to go back to your original
  95 channel.
  96 :::
  97
  98 ## Automatic Upgrades {#sec-upgrading-automatic}
  99
 100 You can keep a NixOS system up-to-date automatically by adding the
 101 following to `configuration.nix`:
 102
 103 ```nix
 104 system.autoUpgrade.enable = true;
 105 system.autoUpgrade.allowReboot = true;
 106 ```
 107
 108 This 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
 111 in the current channel. (To see when the service runs, see `systemctl list-timers`.)
 112 If `allowReboot` is `true`, then the system will automatically reboot if
 113 the new generation contains a different kernel, initrd or kernel
 114 modules. You can also specify a channel explicitly, e.g.
 115
 116 ```nix
 117 system.autoUpgrade.channel = https://nixos.org/channels/nixos-22.11;
 118 ```