Home Manager

Home Manager provides additional functionality to configure user environments in NixOS.

Home Manager outputs

Home Manager options can be used with the Home Manager module or Home Manager configuration flake output types.

Home Manager modules are used to set Home Manager configurations not tied to a specific user. They are useful for organizing your Home Manager settings and to share them between users.
Home Manager configurations are used to set Home Manager options for specific users only.

Home Manager modules and Home Manager configurations can both import other Home Manager modules (see Imports).

When generating Nix code for NixOS configuration and NixOS generate output types, the following will be added if a Home Manager configuration is detected a direct or indirect import:

The home-manager NixOS module exported by the home-manager flake.
A NixOS module with the settings:
home-manager.useGlobalPkgs = true; and
home-manager.useUserPackages = true;

How to use Home Manager in flakes

This short guide will explain how to use Home Manager options with flakes for a user named joe.

Step 1 - Create your flake

Create a flake by signing in to MyNixOS, and then use the create flake page.
Click the flake selector to the upper right, then select the "Outputs" tab on the flake page.
Create three flake outputs: 1) a Home Manager configuration with username joe and system x86_64-linux, 2) a NixOS module named user-joe, and 3) a NixOS configuration named nixos with system x86_64-linux.

Learn about how to assign option values.

Step 2 - Configure the Home Manager configuration output `joe`

This configuration unit is needed to assign Home Manager option values for our user joe.

Set programs.jq.enable to true.
This will enable a the jq utility in the Home Manager environment of joe.
Set home.stateVersion to 22.11.
This is a required configuration which describes the versioning of Home Manager state.

Step 3 - Configure the NixOS module `user-joe`

This configuration unit is needed to assign NixOS option values for our user joe.

Set users.users.<name>.isNormalUser to true for the key joe.
This will enable a user account with username joe.
Set users.users.<name>.password to joe for the key joe.
This will set the password for the joe user to joe.
Add the joe Home Manager configuration as an import to the user-joe NixOS module, by hovering the user-joe NixOS module and using the "Import" button shown with a downward arrow.

Step 4 - Configure the NixOS configuration `nixos`

This configuration unit is needed to describe our NixOS operating system output.

Set system.stateVersion to 22.11.
This is a required configuration which describes the versioning of NixOS state.
Add the user-joe NixOS module as an import to the nixos NixOS configuration, by hovering the nixos NixOS configuration and using the "Import" button shown with a downward arrow.

The resulting flake output configuration is shown below.

Step 5 - Test the NixOS configuration

If you are using NixOS, the NixOS configuration can be tested as below - otherwise, see Release and Install.

Navigate to the flake versions screen (Click the flake selector, then select "Versions").
Click "Release" to create a version of your flake (Learn about releases)
When the release is ready, a new version entry appears in the listing on the flake versions page.
Copy the "Latest" flake URL from the flake versions screen.
Run nixos-rebuild build-vm --flake <latest-flake-url> with the URL and #nixos fragment.
Run ./result/bin/run-nixos-vm
Log in with username joe and password joe.

Congratulations! You are now running a NixOS operating system with Home Manager.

To celebrate, run the jq command enabled by Home Manager.

External information

Home Manager documentation