My NixOS Journey - Home Manager
In the last post I talked about installing NixOS and how you can find the packages and settings to be used on /etc/nixos/configurations.nix
. If you care about setting up user profile declaratively, you will find home manager very quickly. Home manager can be used to not only install user specific packages but also manage application configurations. Some of them are not configurable via nixos options. (dconf.settings is a good example).
You can find home manager official doc here.
In today’s post, I will show you how to start using home manager. Let’s get started.
Installation
On NixOS you have two choices to install Home manager, either as NixOS module or in standalone mode. From my understanding, here are the pros/cons to use home manager as nixos module.
Pros:
- You can easily backup, rollback and set up the entire system with a single
nixos
command.
Cons:
- Making changes to home manager settings results in a whole system level rebuild, users end up having too many generations.
Install as Nix Module
If you want to install home manager as standalone mode, you can go here.
I will follow what is on the official documentation first and then show you how to optimize your config.
Add home manager channel
Let’s run below command to add 22.11
channel first.
1 | sudo nix-channel --add https://github.com/nix-community/home-manager/archive/release-22.11.tar.gz home-manager |
Add hm to config
Next we need to add home manager to /etc/nixos/configuration.nix
. Let’s open this file in text editor and
- Add
<home-manager/nixos>
under imports - Set
users.users.<name>.isNormalUser = true;
(in my case this is already true) - Add
home-manager.users.<name> = { pkgs, ... }: {
related config as below
1 | ... |
Let’s rebuild and the command should work this time. We can use http
to verify httpie is installed.
1 | [fomm@nixos:~]$ http --version |
Above example is pretty self-explanatory. It use home-manager for user.<name>
and installs atool and httpie for this user.
If we take a look at where http is installed, we should see it is installed under my user’s home directory.
1 | [fomm@nixos:~]$ which http |
As home manager configs are for a specific user, let’s split its configs from the main system configuration.
Separate configs
On the official documentation it mentioned there should be a home.nix
but we don’t have this file when we install home manager as NixOS module. Let’s manually create home.nix
with below config in /etc/nixos/
folder.
1 | { config, pkgs, ... }: |
Then we need to change home-manager
part on /etc/nixos/configuration.nix
to below. I also enable useGlobalPkgs and useUserPackages here. Please have a read if you want to know what these two variables do.
1 | ... |
Let’s run sudo nixos-rebuild switch
to rebuild. Because we removed home.packages = [ pkgs.atool pkgs.httpie ];
with above changes, atool and httpie will also be removed. We can verify this as below.
1 | [fomm@nixos:~]$ which http |
Let’s move on to the next section to learn how to use home manager.
Install in standalone mode
Running home manager in standalone mode means you will use home-manager
command to mange home manager related configs.
Add home manager channel
Let’s run below command to add 22.11
channel first.
1 | sudo nix-channel --add https://github.com/nix-community/home-manager/archive/release-22.11.tar.gz home-manager |
Install Home manager
To install, we just need to run below command.
1 | nix-shell '<home-manager>' -A install |
Use home manager
Config folders (where we can find home.nix
):
- NixOS module:
/etc/nixos
- Standalone:
~/.config/nixpkgs/
Update nix channel:
- NixOS:
sudo nix-channel --update
- Home manager:
nix-channel --update
Apply home manager changes command:
- NixOS module:
sudo nixos-rebuild switch
- Standalone:
home-manager switch
Install Nix Packages
We can install nix package by putting the package name under home.packages
on home.nix
. Let’s open this file and add below, this will install htop.
1 | ... |
Once it we rebuild, we should have htop.
1 | [fomm@nixos:~]$ htop --version |
Home manager configs
Now that we know how to install packages, let’s explore how to use Home manager to manage application configurations .
Let’s add below to home.nix
and then run switch command to install.
1 | ... |
This is pretty self-explanatory.
- Install zsh, fzf.
- Enable syntax highlighting, completion and auto suggestion.
- Install oh-my-zsh, use dst theme and docker-compose, docker plugin.
Ctrl + f
to accept autosuggestion.
To find more home manager configs, the first place we can check is the manual page. We may also find some useful information from NixOS Wiki.
Now that zsh is installed, we can run zsh
and we should see all the config above are working. We might also want to set zsh as our default shell. From NixOS Wiki page, we know w need to add below to /etc/nixos/configuration.nix
.
1 | users.users.<name>.shell = pkgs.zsh; |
Let’s add these config and run sudo nixos-rebuild switch
. The next time we log in to our terminal, we should see zsh is used.
Split HM configs
As you can imagine, the more home manager configs we need to use, the longer home.nix
will be which makes managing this file very difficult in the future. What we can do is to split home.nix
and put programs configs to different files and then import it back to home.nix
.
Let’s create /apps
folder in our config folder. Then we can create a zsh.nix
file and put below content on it.
1 | { |
Next let’s go back to home.nix
file and remove the programs.zsh
section and import zsh.nix
back.
1 | { config, pkgs, ... }: |
Let’s rebuild again and we should see zsh is still running fine.
Let’s do one more thing by removing micro editor from system package and use home manager to manage it.
Let’s comment out micro under
environment.systemPackages
on/etc/nixos/configuration.nix
.Then we can create a micro.nix file under home manager
/apps
folder with below content.1
2
3
4
5
6
7
8
9
10
11
12
13
14{
programs.micro = {
enable = true;
settings = {
colorscheme = "material-tc";
mkparents = true;
softwrap = true;
tabmovement = true;
tabsize = 2;
tabstospaces = true;
autosu = true;
};
};
}Then we can can add
./apps/micro.nix
tohome.nix
and rebuild. We will get below error message. This is because we have~/.config/micro/settings.json
from previous installation, home manager wantss you to confirm if you need to backup.1
2Existing file '/home/fomm/.config/micro/settings.json' is in the way of '/nix/store/78gyysv4v3wdkds5l50nv2vbiqj2avnk-home-manager-files/.config/micro/settings.json'
Please move the above files and try again or use 'home-manager switch -b backup' to back up existing files automatically.Since I will use home manager to manage configs for micro, I delete the file and rebuild again. Rebuild should be successful this time. If we use micro again, we can see the indentation, colour theme are working exactly as our configs above.
That’s all I want to share with you today. I hope you can start building your nix configuration using home manager.
See you next time.