NixOS Dist Upgrade

by|inArticles||2 min read

As many other Linux distros NixOS has as well its major releases. If you are new to NixOS and would like to know how to upgrade from one major release - let's say 21.11 - to another (22.05), you are in the right place, let's start.

I am pretty sure that you already found out about the nixos-rebuild command. This command has an --upgrade option, which will upgrade your dependencies. But it is not going to switch your system from one major release to another.

sudo nixos-rebuild switch --upgrade

A major release upgrade is prevented by how nixos is designed. We have a concept of channels. Channels define which group of dependencies can be fetched. And there is a command for it:

sudo nix-channel --list

This command will list all your configured channels for your system (hence, for all users). It is possible to configure channels only for your user, but this will only affect the packages you install via nix-env. Usually it is not needed to configure channels for your current user (since it would be another advanced topic). If no user channels are configured, the channel configuration from root will be used. And we will modify those now. 

What we need is to update the channel location of the channel which is tagged nixos. The list command should show you something like this as a result:


Let's remove this entry by running the command with the remove option and adding a new path with the add option:

sudo nix-channel --remove nixos
sudo nix-channel --add nixos nixos

When using the add option we need to take care to set the tag to nixos. The channel which is tagged by nixos will be used by our nixos-rebuild command. But before, we need to tell NixOS to apply our changes in channels and re-fetch the new information (apt get update in Ubuntu if you want).

sudo nix-channel --update

Now, we are ready to run the nixos-rebuild command:

sudo nixos-rebuild switch --upgrade

This step should finally do the dist upgrade of your NixOS system. Furthermore you could as well run the garbage collection, which I describe here: NixOS - How to remove old generations. But I strongly recommend to reboot your system before and verify that everything works as you expect. If there is a problem - thanks to nix - you can switch back to the version before you have run the dist upgrade, fix the problems (or find a solution) and then do the switch after.

Thank you for reading this far! Let’s connect. You can @ me on Twitter (@debilofant) with comments, or feel free to follow. Please like/share this article so that it reaches others as well.

Related Articles

© Copyright 2023 - - All rights reservedVer. 402