How do I upgrade Nixos to use a new channel nixos version?

Question

I'm currently on 18.03 and would like to upgrade to 18.09. How would I go about doing this?

I've found the following via a web search but it's not very conclusive: https://discourse.nixos.org/t/how-to-upgrade-from-18-03-to-18-09/933

I'm assuming I could possibly just change my channel referenced by nixos? But I'm not sure if this is ideal for allowing to rollback in the case of things going wrong.

sudo nix-channel --list        
nixos https://nixos.org/channels/nixos-18.03
unstable https://nixos.org/channels/nixos-unstable

In addition I've also seen the following: https://github.com/NixOS/nixpkgs/issues/40351#issuecomment-388405973 (quoted below) - do I need to take this into consideration?

Also:

/etc/nixos/configuration.nix:

# This value determines the NixOS release with which your system is to be # compatible, in order to avoid breaking some software such as database # servers. You should change this only after NixOS release notes say you # should. system.stateVersion = "17.09"; # Did you read the comment? I didn't saw when command was issued to change this.

I read the release notes, news and available information. Waited for the command to do it, but not found one.

Anyway, couple days after release I changed "17.09" -> "18.03".

Solution

To upgrade NixOS:

1. Ensure you have a backup of your NixOS installation and that you know how to restore from the backup, if the need arises.
2. Review the NixOS release notes to ensure you account for any changes that need to be done manually. In particular, sometimes options change in backward-incompatible ways.
3. As the root user, replace the NixOS channel so it points to the one you want to upgrade to, while ensuring it is named nixos:

   nix-channel --add https://nixos.org/channels/nixos-18.09 nixos
   

   and update the channel (nix-channel --update).
4. As the root user, build your system:

   nixos-rebuild --upgrade boot
   

5. Reboot to enter your newly-built NixOS.

If things go wrong you can reboot, select the previous generation, use nix-channel to add the old channel, and then nixos-rebuild boot to make the working generation the default; I think it's more reliable to rebuild than to use nixos-rebuild --rollback.

Alternative process

If you want to try the upgrade without messing around with channels, you can use a GIT clone of the nixpkgs repo:

cd nixpkgs
git checkout release-18.03
nixos-rebuild -I nixpkgs="$PWD" build

If all is well...

sudo nixos-rebuild -I nixpkgs="$PWD" boot

The downside to this approach is that subsequent calls to Nix tools, such as nixos-rebuild, require the -I flag to specify the correct nixpkgs.  That is, until you update the channel.

Comments

[GAD3R]

Welcome, After reading the documentation Chapter 4. Upgrading NixOS , the first step you should run all the listed commands as user (without sudo) any change will affect only the user then you can perform an upgrade for the root. Could you confirm?

[Admin]

About system.stateVersion: on more recent installs, the comment on it is clearer: "This value determines the NixOS release from which the default settings for stateful data, like file locations and database versions on your system were taken. It's perfectly fine and recommended to leave this value at the release version of the first install of this system." So generally you should not change it.

[Vladimír Čunát]

I'd add that: (a) /root/.nix-channels and ~/.nix-channels (if used) are trivially editable files, i.e. you can simply skip using nix-channel command except --update to that or to nixos-rebuild; (b) read at least the compatibility section of release notes; (c) most people don't really need backups at that point, as the old system will keep bootable from grub and it's easy to roll back from almost all screw-ups.