How to configure home-manager on NixOS?

Before posting this, I explained how install and remove packages in NixOS for a single station system.

But if you’re using multiple users, there’s a great way to cater to each user’s needs separately.

And in this guide, I will explain how you can set up a home manager on NixOS and how it can be used to install packages.

If you’re new here, some resources covered in this series include:

Configure home-manager on NixOS

In this guide, I will walk you through 2 ways to set up a home manager:

• Standalone Home Manager (uses separate configuration file)
• As a nix module (using it inside configuration.nix to file)

So let’s start with the standalone option.

Standalone installation of home-manager

If you are using a NixOS stable channel, you can use the following command to configure the home manager:

nix-channel --add https://github.com/nix-community/home-manager/archive/release-22.11.tar.gz home-manager

At the time of writing this guide, the stable version is 22.11.

And if you are on an unstable channeluse the following:

nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager

The following steps will remain the same whether you are using stable or unstable.

Once done, update the strings:

nix-channel --update

And finally, use the following command to install the home manager:

nix-shell '<home-manager>' -A install

🛠️ During installation, it may generate the following error:

Restart your system and use the install command again, and the installation will start.

Once done, it will display the location of the home manager standalone installation:

Install home-manager as a NixOS module

If you are on a stable channel (as of writing it is 22.11), you can use the following command to add the home manager stable channel:

sudo nix-channel --add https://github.com/nix-community/home-manager/archive/release-22.11.tar.gz home-manager

And if you are using unstable or the master channeluse the following:

sudo nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager

Once you are done adding a channel using one of the above commands, update the channel using the following:

sudo nix-channel --update

Then open the configuration.nix file using:

sudo nano /etc/nixos/configuration.nix

And add the following line inside the imports []:

<home-manager/nixos>

Now jump to the end of the line and add the following before }:

home-manager.users.{username} = { pkgs, ... }: {
  home.packages = [  ];
  };

The line above was added to make it easier to install and remove the packages that I’ll show you next.

NOW, save changes and exit nano text editor.

Next, rebuild the configuration and make a change:

sudo nixos-rebuild switch

But if you are on a stable release and you use the above command, you will see the following error:

🛠️ error: option `home-manager.users.user.home.stateVersion’ is used but not set:

To solve this problem, you will need to add the home.stateVersion in your home manager block.

As I write, I’m running 22.11, so the whole house manager block would look like this:

home-manager.users.{username} = { pkgs, ... }: {
home.stateVersion = "22.11";  
home.packages = [ ];
  };

Save changes and exit nano text editor by pressing Ctrl + Oby pressing Enter and Ctrl + X.

Now try rebuilding the config and making the change again, and that should fix the problem.

How to install packages using home-manager on NixOS

Now that home-manager is installed, how to install packages with:

Using a standalone installation of Home-manager

First, open the configuration file using the following:

nano /home/$USER/.config/nixpkgs/home.nix

Go to the end of the line and add the following code block before }:

home.packages = [];

Now all you have to do is write the package name between these two braces.

For example, if I want to install htopI should enter the following:

home.packages = [pkgs.htop];

Yes, usually you will need to add the package name with pkgs.

But if you want to get away with using pkgs. each time you install a new package, modify the syntax of the code block as shown:

home.packages = with pkgs; [];

And now you don’t have to use pkgs. for each facility:

home.packages = with pkgs; [htop];

For example, here I wanted to install htop, firefox and LibreOffice so my home block would look like this:

Once you are done adding your favorite packages, save the configuration file and use the following command to install the packages:

home-manager switch

Using the NixOS Module

First, open the configuration.nix file using the following command:

sudo nano /etc/nixos/configuration.nix

In the configuration part, I have already added the home manager block, so all that remains is to add the package name inside home.packages = [  ]; in the displayed format:

home.packages = [ pkgs.package_name ];

For example, if I want install htopFirefox and LibreOffice, then I’ll add:

pkgs.htop pkgs.firefox pkgs.libreoffice

And my house manager block would look like this:

Now save changes and exit the text editor.

Then rebuild the configuration and make a change using the following command:

sudo nixos-rebuild switch

That’s it! The packages will be installed in no time.

It is the end

I think you should go for the standalone install, because you don’t have to use superuser privileges. Also, having separate configuration files for separate users is very handy if you are running a system with multiple users.

So unless you want one file for each purpose, I see no other reason to use the module option.

With this, I conclude the NixOS Beginner Series. I hope this will give you a good enough platform to familiarize yourself with this unique Linux distro.

💬 How did you like the NixOS series? Anything else we should cover for NixOS newbies? Please provide your valuable feedback.