- Preface
- 1. Installing Home Manager
- 2. Writing Home Manager Modules
- 3. Contributing
- 3.1. Getting started
- 3.2. Guidelines
- 3.2.1. Maintain backward compatibility
- 3.2.2. Keep forward compatibility in mind
- 3.2.3. Add only valuable options
- 3.2.4. Add relevant tests
- 3.2.5. Add relevant documentation
- 3.2.6. Add yourself as a module maintainer
- 3.2.7. Format your code
- 3.2.8. Format your commit messages
- 3.2.9. Format your news entries
- 3.2.10. Use conditional modules and news
- 3.2.11. Mind the license
- 3.3. Commits
- 3.4. Code Style
- 3.5. News
- 3.6. Tests
- 4. Frequently Asked Questions (FAQ)
- 4.1. Why is there a collision error when switching generation?
- 4.2. Why are the session variables not set?
- 4.3. How to set up a configuration for multiple users/machines?
- 4.4. Why do I get an error message about
ca.desrt.dconf? - 4.5. How do I install packages from Nixpkgs unstable?
- 4.6. How do I override the package used by a module?
- A. Configuration Options
- B. NixOS Module Options
- C. nix-darwin Module Options
- D. Tools
- home-manager - — reconfigure a user environment
- E. Release Notes
+
- Preface
- 1. Installing Home Manager
- 2. Using Home Manager
- 3. Writing Home Manager Modules
- 4. Contributing
- 4.1. Getting started
- 4.2. Guidelines
- 4.2.1. Maintain backward compatibility
- 4.2.2. Keep forward compatibility in mind
- 4.2.3. Add only valuable options
- 4.2.4. Add relevant tests
- 4.2.5. Add relevant documentation
- 4.2.6. Add yourself as a module maintainer
- 4.2.7. Format your code
- 4.2.8. Format your commit messages
- 4.2.9. Format your news entries
- 4.2.10. Use conditional modules and news
- 4.2.11. Mind the license
- 4.3. Commits
- 4.4. Code Style
- 4.5. News
- 4.6. Tests
- 5. Frequently Asked Questions (FAQ)
- 5.1. Why is there a collision error when switching generation?
- 5.2. Why are the session variables not set?
- 5.3. How to set up a configuration for multiple users/machines?
- 5.4. Why do I get an error message about
ca.desrt.dconf? - 5.5. How do I install packages from Nixpkgs unstable?
- 5.6. How do I override the package used by a module?
- A. Configuration Options
- B. NixOS Module Options
- C. nix-darwin Module Options
- D. Tools
- home-manager + — reconfigure a user environment
- E. Release Notes
This manual will eventually describe how to install, use, and extend Home Manager.
@@ -115,7 +115,118 @@ configured via the home-manager.users.<name>.nixpkgs
instead use the global pkgs that is configured via the system level
nixpkgs options, set
home-manager.useGlobalPkgs = true;
This saves an extra Nixpkgs evaluation, adds consistency, and removes
the dependency on NIX_PATH, which is otherwise used for importing
-Nixpkgs.
The module system in Home Manager is based entirely on the NixOS module system so we will here only highlight aspects that are specific for Home Manager. For information about the module system as such please refer to the Writing NixOS Modules chapter of the NixOS manual.
Overall the basic option types are the same in Home Manager as NixOS. A few Home Manager options, however, make use of custom types that are worth describing in more detail. These are the option types dagOf and gvariant that are used, for example, by programs.ssh.matchBlocks and dconf.settings.
- +Nixpkgs.
Your use of Home Manager is centered around the configuration file, which is typically found at ~/.config/nixpkgs/home.nix.
This configuration file can be built and activated.
Building a configuration produces a directory in the Nix store containing all files and programs that should be available in your home directory and Nix user profile, respectively. The build step also checks that the configuration is valid and it will fail with an error if you, for example, assign a value to an option that does not exist or assign a value of the wrong type. Some modules also have custom assertions that perform more detailed, module specific, checks.
Concretely, if your configuration contains
programs.emacs.enable = "yes";
then building it, for example using home-manager build, will result in an error message saying something like
$ home-manager build +error: A definition for option `programs.emacs.enable' is not of type `boolean'. Definition values: +- In `/home/jdoe/.config/nixpkgs/home.nix': "yes" +(use '--show-trace' to show detailed location information)
The message indicates that you must provide a Boolean value for this option, that is, either true or false. The documentation of each option will state the expected type, for programs.emacs.enable you will see “Type: boolean”. You there also find information about the default value and a description of the option. You can find the complete option documentation in Appendix A, Configuration Options or directly in the terminal by running
man home-configuration.nix
Once a configuration is successfully built, it can be activated. The activation performs the steps necessary to make the files, programs, and services available in your user environment. The home-manager switch command performs a combined build and activation.
A fresh install of Home Manager will generate a minimal ~/.config/nixpkgs/home.nix file containing something like
{ config, pkgs, ... }:
+
+{
+ # Home Manager needs a bit of information about you and the
+ # paths it should manage.
+ home.username = "jdoe";
+ home.homeDirectory = "/home/jdoe";
+
+ # This value determines the Home Manager release that your
+ # configuration is compatible with. This helps avoid breakage
+ # when a new Home Manager release introduces backwards
+ # incompatible changes.
+ #
+ # You can update Home Manager without changing this value. See
+ # the Home Manager release notes for a list of state version
+ # changes in each release.
+ home.stateVersion = "21.11";
+
+ # Let Home Manager install and manage itself.
+ programs.home-manager.enable = true;
+}You can use this as a base for your further configurations.
Note
If you are not very familiar with the Nix language and NixOS modules then it is encouraged to start with small and simple changes. As you learn you can gradually grow the configuration with confidence.
As an example, let us expand the initial configuration file to also install the htop and fortune packages, install Emacs with a few extra packages available, and enable the user gpg-agent service.
To satisfy the above setup we should elaborate the home.nix file as follows:
{ config, pkgs, ... }:
+
+{
+ # Home Manager needs a bit of information about you and the
+ # paths it should manage.
+ home.username = "jdoe";
+ home.homeDirectory = "/home/jdoe";
+
+ # Packages that should be installed to the user profile.
+ home.packages = [ 
+ pkgs.htop
+ pkgs.fortune
+ ];
+
+ # This value determines the Home Manager release that your
+ # configuration is compatible with. This helps avoid breakage
+ # when a new Home Manager release introduces backwards
+ # incompatible changes.
+ #
+ # You can update Home Manager without changing this value. See
+ # the Home Manager release notes for a list of state version
+ # changes in each release.
+ home.stateVersion = "21.11";
+
+ # Let Home Manager install and manage itself.
+ programs.home-manager.enable = true;
+
+ programs.emacs = { 
+ enable = true;
+ extraPackages = epkgs: [
+ epkgs.nix-mode
+ epkgs.magit
+ ];
+ };
+
+ services.gpg-agent = { 
+ enable = true;
+ defaultCacheTtl = 1800;
+ enableSshSupport = true;
+ };
+}
|
+Nixpkgs packages can be installed to the user profile using |
|
+The option names of a program module typically start with |
|
+Similarly, for a service module, the names start with |
To activate this configuration you can run
home-manager switch
or if you are not feeling so lucky,
home-manager build
which will create a result link to a directory containing an
+activation script and the generated home directory files.
While the home-manager tool does not explicitly support rollbacks at the moment it is relatively easy to perform one manually. The steps to do so are
+Run
home-manager generationsto determine which generation you wish to rollback to: +$ home-manager generations +2018-01-04 11:56 : id 765 -> /nix/store/kahm1rxk77mnvd2l8pfvd4jkkffk5ijk-home-manager-generation +2018-01-03 10:29 : id 764 -> /nix/store/2wsmsliqr5yynqkdyjzb1y57pr5q2lsj-home-manager-generation +2018-01-01 12:21 : id 763 -> /nix/store/mv960kl9chn2lal5q8lnqdp1ygxngcd1-home-manager-generation +2017-12-29 21:03 : id 762 -> /nix/store/6c0k1r03fxckql4vgqcn9ccb616ynb94-home-manager-generation +2017-12-25 18:51 : id 761 -> /nix/store/czc5y6vi1rvnkfv83cs3rn84jarcgsgh-home-manager-generation +…
+Copy the Nix store path of the generation you chose, e.g., +
/nix/store/mv960kl9chn2lal5q8lnqdp1ygxngcd1-home-manager-generation
for generation 763.
+Run the
activatescript inside the copied store path: +$ /nix/store/mv960kl9chn2lal5q8lnqdp1ygxngcd1-home-manager-generation/activate +Starting home manager activation +…
To configure programs and services Home Manager must write various things to your home directory. To prevent overwriting any existing files when switching to a new generation, Home Manager will attempt to detect collisions between existing files and generated files. If any such collision is detected the activation will terminate before changing anything on your computer.
For example, suppose you have a wonderful, painstakingly created ~/.config/git/config and add
{
+ # …
+
+ programs.git = {
+ enable = true;
+ userName = "Jane Doe";
+ userEmail = "jane.doe@example.org";
+ };
+
+ # …
+}to your configuration. Attempting to switch to the generation will then result in
$ home-manager switch +… +Activating checkLinkTargets +Existing file '/home/jdoe/.config/git/config' is in the way +Please move the above files and try again
Home Manager includes a number of services intended to run in a graphical session, for example xscreensaver and dunst. Unfortunately, such services will not be started automatically unless you let Home Manager start your X session. That is, you have something like
{
+ # …
+
+ services.xserver.enable = true;
+
+ # …
+}in your system configuration and
{
+ # …
+
+ xsession.enable = true;
+ xsession.windowManager.command = "…";
+
+ # …
+}in your Home Manager configuration.
The module system in Home Manager is based entirely on the NixOS module system so we will here only highlight aspects that are specific for Home Manager. For information about the module system as such please refer to the Writing NixOS Modules chapter of the NixOS manual.
Overall the basic option types are the same in Home Manager as NixOS. A few Home Manager options, however, make use of custom types that are worth describing in more detail. These are the option types dagOf and gvariant that are used, for example, by programs.ssh.matchBlocks and dconf.settings.
-
hm.types.dagOf Options of this type have attribute sets as values where each member is a node in a directed acyclic graph (DAG). This allows the attribute set entries to express dependency relations among themselves. This can, for example, be used to control the order of match blocks in a OpenSSH client configuration or the order of activation script blocks in
home.activation. @@ -243,23 +354,23 @@ Builds a GVariant maybe value containing the given GVariant element.hm.gvariant.mkTuple elements- Builds a GVariant tuple containing the given list of elements, where each element is a GVariant value. -