Chapter 3 - Home Manager

Home Manager (often abbrevieted to HM) is a project similar to NixOS, but for a specific user’s home folder. You use NixOS to manage system programs, configuration, etc. But Home Manager is programs and configuration for a specific user.

In this chapter we will…

Add Home Manager as an input to our flake
Learn how to add home manager modules
Configure our .face file with home manager as an example

Adding Home Manager as an Input

First we need to add Home Manager as an input to our flake.

In flake.nix, add a new attr set to the inputs attr set called home-manager (this can technically be called whatever you like, some people shorten this to hm).
flake.nix
```
inputs = {
  nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
  home-manager = {
      url = "github:nix-community/home-manager";
      inputs.nixpkgs.follows = "nixpkgs";
  };
};
```
This tells Nix two things:
1. We have an input named home-manager that should be fetched from the nix-community/home-manager GitHub repo.
2. The Home Manager flake itself depends on nixpkgs as an input. To keep thing consistent, we tell Nix that input should follow our nixpkgs input.

Now, we add home-manager as an argument to our outputs function.

outputs = inputs @ {
  self,
  nixpkgs,
  home-manager,
} let ... in {
  # ...
}

We now have access to home manager in our flake!

Telling NixOS About Home Manager

Now we need NixOS to access home manager. In our modules list we’ll add home-manager.nixosModules.home-manager.

modules = [
  ./modules/config.nix
  home-manager.nixosModules.home-manager
];

This will load additional options into NixOS to let us use home manager.

Configuring Home Manager

Now we’re ready to start using Home Manager within our NixOS config.

In config.nix (or a separate module if you feel like it). Create a new attr set called home-manager.

We’re going to fill this with our home config, replace YOURUSER with your username below.

home-manager = {
  useGlobalPkgs = true; # Sets HM to use the global nixpkgs instance
  useUserPackages = true;
  extraSpecialArgs = { inherit inputs; }; # Pass inputs to HM modules too
  users.YOURUSER = import ../home/home.nix; # Point HM to our root home manager module for user "YOURNAME"
};

Here you can see we’re importing another file (../home/home.nix). This file will hold a home manager module, these are very similar in appearance to NixOS modules so I recommend placing them in a different folder from modules to differentiate them.

Create home/home.nix and fill it with boilerplate for now.

flake.nix
flake.lock
Directorymodules/
- config.nix
- …
Directoryhome/
- home.nix Root HM Module
- …

{pkgs, ...}: {

}

Using Home Manager

First things first we’ll add these options, replace YOURNAME with your username.

{pkgs, ...}: {
  home = {
      username = "YOURUSER";
      homeDirectory = "/home/YOURUSER";
      stateVersion = "24.11";
  };
}

This will tell home manager your username and where your home folder is.

You can split up home manager modules similar to NixOS modules, using the imports option.

flake.nix
flake.lock
Directoryhome/
- home.nix
- some-hm-module.nix

{pkgs, ...}: {
    imports = [ ./some-hm-module.nix ];

    # ...
}

Home Manager Option Search

Example: Adding `.face`

To go into a quick use case for HM, we’ll add a file to the root of our home folder, .face.

This file is used by some programs to know what profile picture to display on various UI components.

Place the image file in your config’s repo (I like to place any non-nix files in a folder called res, for resources).
- flake.nix
- flake.lock
- Directorymodules/
  - …
- Directoryhome/
  - …
- Directoryres/
  - YOURIMAGE.png
Can’t forget to git add of course.
Terminal window
```
git add .
```
In an HM module set up a link, replace YOURIMAGE.png with the name of your image file.
home/home.nix
```
{pkgs, ...}: {
  # ...

  home.file.".face".source = ../res/YOURIMAGE.png;
}
```
Notice how we need to put .face in quotes here. Home Manager accepts any arbitrary string in the file attr set, but since our attr name has a . we need to put in quotes.

We’re once again seeing a path without quotes. In short this tells Nix:

While building, copy this file into the nix store and return a string to that nix store path.

We’ll get into what exactly the Nix store is in another chapter.

Run the VM again and check your home folder, you’ll notice a .face symlink!

Directory/home/user
- …
- .face A symlink to the nix store!