NixOS + Home Manager
Set up the Home Manager tool in NixOS.
Rajdeep Singh · Follow
Published in · 8 min read · Nov 30, 2023
--
Home Manager helps to manage a user-specific environment, like installing additional and config the packages without the need for sudo.
To install a home manager in NixOS, there are three ways. Don't worry in this article we use the Standalone installation method to install Home Manager, and it is a recommended method by NixOS.
The difference between Standalone installation and NixOS module.
In the NixOS module, you write configuration inside the configuration.nix
file and every time you change you need to run the nixos-rebuild command.
Other hand in a Standalone installation, you write the configuration in the .config/home-manager/home.nix
file. Which is provided by the manager, and you do not need to rebuild the entire system.
If you manage multiple users (machines) you act like an admin, then you use the NixOS module. If you install NixOS on a laptop or single machine you can use a standalone installation.
First, check the NixOS version in your system using the nix-info command.
$ nixos nix-info --host-os
system: "x86_64-linux", host os: Linux 6.1.58, NixOS, 23.05 (Stoat), 23.05.4420.679cadfdfed2, multi-user?: yes, version: nix-env (Nix) 2.13.6, channels(root): "nixos-23.05", nixpkgs: /nix/var/nix/profiles/per-user/root/channels/nixos
Installing the Home Manager in NixOS is a very easy process. I use nixos Standalone method.
You need to copy and paste three commands one by one in your terminal. Your Home Manager is successfully installed it takes less than 5 minutes.
- Add Home Manager channel
- Home Manager installation command
To install the NixOS home manager, you know NixOS has two nixpkgs channels.
You can check the list of current nixpkgs channels available in NixOS using the nixos nix-channel
command.
$ nixos nix-channel --list
unstable https://nixos.org/channels/nixpkgs-unstable
nixpkgs https://nixos.org/channels/nixpkgs
By default, the nixos nix-channel
command shows an available channel list, In my case, I also added the unstable channel in NixOS to install the latest version of packages.
The NixOS Home Manager channel is directly based on the Nixpkgs channel. There are two channels available.
- Unstable channel
- Stable channel
Unstable channel
If you install some applications using the unstable Nixpkgs channel, then run the following command.
nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager
nix-channel --update
The command output looks like this.
$ nix-channel --add https://github.com/nix-community/home-manager/archive/release-23.11.tar.gz home-manager
$ nix-channel --update
this derivation will be built:
/nix/store/yqqba6zlvv56mcjvl5l70b2kbiwyas1b-home-manager-23.11.tar.gz.drv
building '/nix/store/yqqba6zlvv56mcjvl5l70b2kbiwyas1b-home-manager-23.11.tar.gz.drv'...
unpacking channels...
Stable channel
You know NixOS has a different version or released, you can find the NixOS version using the nix-info command.
If you have Nixpkgs (NixOS) version 23.11 then run the following command
nix-channel --add https://github.com/nix-community/home-manager/archive/release-23.11.tar.gz home-manager
nix-channel --update
Your command output looks like this
$ nix-channel --add https://github.com/nix-community/home-manager/archive/release-23.11.tar.gz home-manager
$ nix-channel --update
this derivation will be built:
/nix/store/yqqba6zlvv56mcjvl5l70b2kbiwyas1b-home-manager-23.11.tar.gz.drv
building '/nix/store/yqqba6zlvv56mcjvl5l70b2kbiwyas1b-home-manager-23.11.tar.gz.drv'...
unpacking channels...
In my case, the Nixpkgs (NixOS) version is 23.05, I run the following command.
nix-channel --add https://github.com/nix-community/home-manager/archive/release-23.05.tar.gz home-manager
nix-channel --update
Home Manager installation command
After adding the Home Manager channel to your NixOS. The last step is to run the Home Manager installation command.
nix-shell '<home-manager>' -A install
Your command output looks like this.
➜ ~ nix-shell '<home-manager>' -A install
Creating /home/officialrajdeepsingh/.config/home-manager/home.nix...Creating initial Home Manager generation...
these 18 derivations will be built:
/nix/store/1w7gn2s6rw0mc4kqv1jr8a8lbki2i2s5-home-manager.drv
/nix/store/j8qb0rdgc7zpma65v6anl8fglrk6g4p5-python3-3.10.13-env.drv
/nix/store/jwrf5w6iym1x4ras161px28rm3zl2180-options.json.drv
/nix/store/1c20wzirzk1hzphyf5nigba0x80ikgkh-options-db.xml.drv
/nix/store/3sqgj9wrxingnfgq9wpm4fi8misxwr5j-converted-asciidoc.drv
/nix/store/gx4vwsh4h1jvj6k7a87axnddsdawffpn-options.json.drv
/nix/store/h1n225njrkh12mjsyy271sscr586231l-options-db.xml.drv
/nix/store/yjr3m6zyr4ry1ih6nj44p60fy1vbwjlw-options-db.xml.drv
/nix/store/fdc5740wqh92mlqnb0r9n881z2adq5dj-nmd-documents.drv
/nix/store/ivgwk67h8x9nbfq4wsdkgn8s5mfzwxfg-manual-combined.drv
/nix/store/516jp65bik1nsid1rs7brmaip44lvh6l-manual-olinkdb.drv
/nix/store/xlfrziajlf68amz01qjaacg2lxpdn6q4-man-pages.drv
/nix/store/pzrp69vn7vjb1yk03gmbmpnn1axjri3d-home-manager-path.drv
/nix/store/wixf32pm8j80kwjrnhliavvsvhcsw8bz-hm-modules-messages.drv
/nix/store/19rpda7ad9mh9i5s8zywam76c4x6cima-check.drv
/nix/store/7q8mldj4gzqc7p2papnq091jsj2mlk28-cleanup.drv
/nix/store/z2s27ji265f3lsvvshfd2bmiknyg28ci-activation-script.drv
/nix/store/03gzrfh8yvcyisycyw2bvkimzbr1sgzx-home-manager-generation.drv
these 3 paths will be fetched (0.19 MiB download, 0.84 MiB unpacked):
/nix/store/1n0vhgyn7knfq2vdh3z2b5figlj2cin8-python3.10-mistune-2.0.5
/nix/store/31dib4jw373px2d8c0hcmv4xbriaxhwq-nix-2.13.6-dev
/nix/store/v9nrp3rd303arhzdjz7zgpfyi9xpfq3c-boehm-gc-8.2.2-dev
building '/nix/store/wixf32pm8j80kwjrnhliavvsvhcsw8bz-hm-modules-messages.drv'...
building '/nix/store/1w7gn2s6rw0mc4kqv1jr8a8lbki2i2s5-home-manager.drv'...
building '/nix/store/3sqgj9wrxingnfgq9wpm4fi8misxwr5j-converted-asciidoc.drv'...
copying path '/nix/store/v9nrp3rd303arhzdjz7zgpfyi9xpfq3c-boehm-gc-8.2.2-dev' from 'https://cache.nixos.org'...
install: creating directory '/nix/store/g8rnm1lfikycp5bjzqw08kcb2vg6qpy2-home-manager'
install: creating directory '/nix/store/g8rnm1lfikycp5bjzqw08kcb2vg6qpy2-home-manager/bin'
'/nix/store/2fxh8dzsnlqyydfz06smd0iacrmv822k-home-manager' -> '/nix/store/g8rnm1lfikycp5bjzqw08kcb2vg6qpy2-home-manager/bin/home-manager'
copying path '/nix/store/1n0vhgyn7knfq2vdh3z2b5figlj2cin8-python3.10-mistune-2.0.5' from 'https://cache.nixos.org'...
Converting 3rd-party.adoc to DocBook ...
building '/nix/store/19rpda7ad9mh9i5s8zywam76c4x6cima-check.drv'...
building '/nix/store/7q8mldj4gzqc7p2papnq091jsj2mlk28-cleanup.drv'...
Converting contributing.adoc to DocBook ...
Converting faq.adoc to DocBook ...
Converting installation.adoc to DocBook ...
Converting nix-flakes.adoc to DocBook ...
copying path '/nix/store/31dib4jw373px2d8c0hcmv4xbriaxhwq-nix-2.13.6-dev' from 'https://cache.nixos.org'...
building '/nix/store/j8qb0rdgc7zpma65v6anl8fglrk6g4p5-python3-3.10.13-env.drv'...
Converting usage.adoc to DocBook ...
created 218 symlinks in user environment
Converting writing-modules.adoc to DocBook ...
Converting release-notes/release-notes.adoc to DocBook ...
Converting release-notes/rl-1809.adoc to DocBook ...
Converting release-notes/rl-1903.adoc to DocBook ...
Converting release-notes/rl-1909.adoc to DocBook ...
Converting release-notes/rl-2003.adoc to DocBook ...
building '/nix/store/gx4vwsh4h1jvj6k7a87axnddsdawffpn-options.json.drv'...
building '/nix/store/jwrf5w6iym1x4ras161px28rm3zl2180-options.json.drv'...
Converting release-notes/rl-2009.adoc to DocBook ...
building '/nix/store/h1n225njrkh12mjsyy271sscr586231l-options-db.xml.drv'...
building '/nix/store/yjr3m6zyr4ry1ih6nj44p60fy1vbwjlw-options-db.xml.drv'...
Converting release-notes/rl-2105.adoc to DocBook ...
building '/nix/store/1c20wzirzk1hzphyf5nigba0x80ikgkh-options-db.xml.drv'...
Converting release-notes/rl-2111.adoc to DocBook ...
Converting release-notes/rl-2205.adoc to DocBook ...
Converting release-notes/rl-2211.adoc to DocBook ...
Converting release-notes/rl-2305.adoc to DocBook ...
building '/nix/store/fdc5740wqh92mlqnb0r9n881z2adq5dj-nmd-documents.drv'...
created 44 symlinks in user environment
building '/nix/store/ivgwk67h8x9nbfq4wsdkgn8s5mfzwxfg-manual-combined.drv'...
/nix/store/v0z2jbp1d5fkj3hvz5ybgzkh1j42vswm-manual-combined/manual-combined.xml validates
/nix/store/v0z2jbp1d5fkj3hvz5ybgzkh1j42vswm-manual-combined/man-pages-combined.xml validates
building '/nix/store/516jp65bik1nsid1rs7brmaip44lvh6l-manual-olinkdb.drv'...
Writing /nix/store/qa74x6hk172wnax017zw7ab3z8vlsjpq-manual-olinkdb/manual.db for book(book-home-manager-manual)
building '/nix/store/xlfrziajlf68amz01qjaacg2lxpdn6q4-man-pages.drv'...
Warn: AUTHOR sect.: no personblurb|contrib for Home Manager contr
Note: AUTHOR sect.: see http://www.docbook.org/tdg5/en/html/contr
Note: AUTHOR sect.: see http://www.docbook.org/tdg5/en/html/perso
Note: Writing /nix/store/b07f7abvy8jmsnr9akcnd8nn39sk32q3-man-pages/share/man/man5/home-configuration.nix.5
Warn: AUTHOR sect.: no personblurb|contrib for Home Manager contr
Note: AUTHOR sect.: see http://www.docbook.org/tdg5/en/html/contr
Note: AUTHOR sect.: see http://www.docbook.org/tdg5/en/html/perso
Note: Writing /nix/store/b07f7abvy8jmsnr9akcnd8nn39sk32q3-man-pages/share/man/man1/home-manager.1
gzipping man pages under /nix/store/b07f7abvy8jmsnr9akcnd8nn39sk32q3-man-pages/share/man/
building '/nix/store/pzrp69vn7vjb1yk03gmbmpnn1axjri3d-home-manager-path.drv'...
created 205 symlinks in user environment
building '/nix/store/z2s27ji265f3lsvvshfd2bmiknyg28ci-activation-script.drv'...
building '/nix/store/03gzrfh8yvcyisycyw2bvkimzbr1sgzx-home-manager-generation.drv'...
/nix/store/j8ri9sl25lwnfw4zma4sx9ag4vc93977-home-manager-generation
Starting Home Manager activation
Activating checkFilesChanged
Activating checkLinkTargets
Activating writeBoundary
Activating installPackages
installing 'home-manager-path'
building '/nix/store/ji2rk8688rlh0j6fsvcr1yqrbwb3v0zr-user-environment.drv'...
Activating linkGeneration
Creating profile generation 1
Creating home file links in /home/officialrajdeepsingh
Activating onFilesChange
Activating reloadSystemd
There are 94 unread and relevant news items.
Read them by running the command "home-manager news".
All done! The home-manager tool should now be installed and you can edit
/home/officialrajdeepsingh/.config/home-manager/home.nix
to configure Home Manager. Run 'man home-configuration.nix' to
see all available options.
Now your home manager is successfully installed in your NixOS. You can use it.
If you are new to NixOS, you face some errors during Home Manager installation. I can tell you the solution.
Error 1: trace: warning: You are using Home Manager version 24.05 and Nixpkgs version 23.05.
The error is shown because the Home Manager version and
NixOS (Nixpkgs) version difference. Your NixOS version is 23.05, and you install Home Manager version 24.05.
The solution is first to check the current version of NixOS on your laptop using the nix-info command. Based on the version you install home manager.
For example, your current NixOS version is 23.05, you need to install Home Manager version 23.05.
➜ nix-shell '<home-manager>' -A install
this derivation will be built:
/nix/store/bs6hcx6r1fv82ni8silils6rfpwi3yqy-home-manager.drv
these 6 paths will be fetched (2.97 MiB download, 15.43 MiB unpacked):
/nix/store/479vwnchw4pn91gr7m2lnla0q8ms96yh-nix-2.3.16
/nix/store/5v4yklgl7y5x47w5z5zqm7sdw2gddpsv-nix-2.3.16-man
/nix/store/cxbkkzryycr8si17jvii6xab4iwadszm-aws-sdk-cpp-1.9.294
/nix/store/ix0gl5z4nb9dhwavfzl491nip5i6hnvd-boehm-gc-8.2.2
/nix/store/m4pliqf1mnqwyln77nl42kssljbsvnni-nixos-option
/nix/store/qv2cgi6pz9p1y3wqql3px1fss76yqwdd-hostname-net-tools-2.10
copying path '/nix/store/5v4yklgl7y5x47w5z5zqm7sdw2gddpsv-nix-2.3.16-man' from 'https://cache.nixos.org'...
copying path '/nix/store/qv2cgi6pz9p1y3wqql3px1fss76yqwdd-hostname-net-tools-2.10' from 'https://cache.nixos.org'...
copying path '/nix/store/ix0gl5z4nb9dhwavfzl491nip5i6hnvd-boehm-gc-8.2.2' from 'https://cache.nixos.org'...
copying path '/nix/store/cxbkkzryycr8si17jvii6xab4iwadszm-aws-sdk-cpp-1.9.294' from 'https://cache.nixos.org'...
copying path '/nix/store/479vwnchw4pn91gr7m2lnla0q8ms96yh-nix-2.3.16' from 'https://cache.nixos.org'...
copying path '/nix/store/m4pliqf1mnqwyln77nl42kssljbsvnni-nixos-option' from 'https://cache.nixos.org'...
building '/nix/store/bs6hcx6r1fv82ni8silils6rfpwi3yqy-home-manager.drv'...
install: creating directory '/nix/store/m2fpzcakapwznwdlwn9hzxdhczlslghr-home-manager'
install: creating directory '/nix/store/m2fpzcakapwznwdlwn9hzxdhczlslghr-home-manager/bin'
'/nix/store/8y9r5vmbgz5bx42j4dal63lph6lxs76i-home-manager' -> '/nix/store/m2fpzcakapwznwdlwn9hzxdhczlslghr-home-manager/bin/home-manager'
Creating /home/officialrajdeepsingh/.config/home-manager/home.nix...Creating initial Home Manager generation...
trace: warning: You are using
Home Manager version 24.05 and
Nixpkgs version 23.05.
Using mismatched versions is likely to cause errors and unexpected
behavior. It is therefore highly recommended to use a release of Home
Manager that corresponds with your chosen release of Nixpkgs.
If you insist then you can disable this warning by adding
home.enableNixpkgsReleaseCheck = false;
to your configuration.
Error 2: File ‘home-manager’ was not found
To solve this issue, first run nix-channel --update
command than run nixos nix-shell '<home-manager>' -A install
command.
$ nixos nix-channel --add https://github.com/nix-community/home-manager/archive/release-23.05.tar.gz home-manag➜ nixos nix-shell '<home-manager>' -A install
error: file 'home-manager' was not found in the Nix search path (add it using $NIX_PATH or -I)
at «none»:0: (source not available)
➜ nixos
Error 3: error: A definition for option `home.stateVersion’ is not of type
The following error is shown because some reason our nixos nix-shell '<home-manager>' -A install
command filed. Then we rerun the nixos nix-shell '<home-manager>' -A install
command it shows an error.
To solve this issue first delete or remove the .config/home-manager/home.nix
file, and rerun the nixos nix-shell '<home-manager>' -A install
command, your error is solved.
➜ nix-shell '<home-manager>' -A install
this derivation will be built:
/nix/store/8y476imhkjsia9i9q8pg20wikcsya3g1-home-manager.drv
building '/nix/store/8y476imhkjsia9i9q8pg20wikcsya3g1-home-manager.drv'...
install: creating directory '/nix/store/xbrdwbbgb134ch4lxn38qacj8wgv91z4-home-manager'
install: creating directory '/nix/store/xbrdwbbgb134ch4lxn38qacj8wgv91z4-home-manager/bin'
'/nix/store/2fxh8dzsnlqyydfz06smd0iacrmv822k-home-manager' -> '/nix/store/xbrdwbbgb134ch4lxn38qacj8wgv91z4-home-manager/bin/home-manager'
The file /home/officialrajdeepsingh/.config/home-manager/home.nix already exists, leaving it unchanged...Creating initial Home Manager generation...
error: A definition for option `home.stateVersion' is not of type `one of "18.09", "19.03", "19.09", "20.03", "20.09", "21.03", "21.05", "21.11", "22.05", "22.11", "23.05"'. Definition values:
- In `/home/officialrajdeepsingh/.config/home-manager/home.nix': "23.11"
(use '--show-trace' to show detailed location information)
Uh oh, the installation failed! Please create an issue at
https://github.com/nix-community/home-manager/issues
if the error seems to be the fault of Home Manager.
The NixOS Home Manager tool is my favorite tool. It gives you the power to install the package without rebuilding the entire system.
You can easily manage your user configuration with Home Manager and you do not need to rebuild your system again and again when something changes in configuration.
When I was new in the NixOS ecosystem I used aconfiguration.nix
file to install, configure and delete packages. I create so many builds within a week.
When I change something I rebuild the NixOS. But I know it is not the right way. That way I always recommend using Home Manager if you use NixOS. It takes less than three minutes to install Home Manager in NixOS.