home-manager Documentation

Manage a user environment using Nix [maintainer=@khaneliman, @rycee]

10,155 stars Nix 1 file · ~9,291 tokens #dotfiles#nix#nix-dotfiles#nixos#nixpkgs
RAW Doc

File: README.md

Home Manager using Nix

This project provides a basic system for managing a user environment using the
Nix package manager together with the Nix libraries found in Nixpkgs. It
allows declarative configuration of user specific (non-global) packages and
dotfiles.

Usage

Before attempting to use Home Manager please read the warning
below.

For a systematic overview of Home Manager and its available options, please see:

If you would like to contribute to Home Manager, then please have a look at
"Contributing" in the manual.

Releases

Home Manager is developed against the nixpkgs-unstable branch, which often
causes it to contain tweaks for changes/packages not yet released in stable
NixOS.
To avoid breaking users' configurations, Home Manager is released in branches
corresponding to NixOS releases (e.g. release-26.05). These branches get
fixes, but usually not new modules. If you need a module to be backported, then
feel free to open an issue.

Words of warning

Unfortunately, it is quite possible to get difficult to understand errors when
working with Home Manager. You should therefore be comfortable using the Nix
language and the various tools in the Nix ecosystem.

If you are not very familiar with Nix but still want to use Home Manager then
you are strongly encouraged to start with a small and very simple configuration
and gradually make it more elaborate as you learn.

In some cases Home Manager cannot detect whether it will overwrite a previous
manual configuration. For example, the Gnome Terminal module will write to your
dconf store and cannot tell whether a configuration that is about to be
overwritten was from a previous Home Manager generation or from manual
configuration.

Home Manager targets nixpkgs-unstable and NixOS version 26.05 (the current
stable version), it may or may not work on other Linux distributions and NixOS
versions.

Now when your expectations have been built up and you are eager to try all this
out you can go ahead and read the rest of this text.

Contact

You can chat with us on IRC in the channel #home-manager on OFTC. There
is also a Matrix room, which is bridged to
the IRC channel.

Installation

Home Manager can be used in three primary ways:

  1. Using the standalone home-manager tool. For platforms other than NixOS and
    Darwin, this is the only available choice. It is also recommended for people
    on NixOS or Darwin that want to manage their home directory independently
    of the system as a whole. See "Standalone installation" in the
    manual     for instructions on how to perform this
    installation.

  2. As a module within a NixOS system configuration. This allows the user
    profiles to be built together with the system when running nixos-rebuild.
    See "NixOS module" in the manual for a description of
    this setup.

  3. As a module within a nix-darwin system configuration. This allows the user
    profiles to be built together with the system when running darwin-rebuild.
    See "nix-darwin module" in the manual for a
    description of this setup.

Home Manager provides both the channel-based setup and the flake-based one. See
Nix Flakes for a description of the flake-based setup.

Translations

Home Manager has basic support for internationalization through
gettext. The translations are hosted by
Weblate. If you would like to contribute to the
translation effort then start by going to the Home Manager Weblate
project.

License

This project is licensed under the terms of the MIT license.

File: docs/manual/3rd-party/collections.md

Module Collections {#sec-3rd-party-module-collections}

File: docs/manual/contributing/getting-started.md

Getting started {#sec-contrib-getting-started}

If you have not previously forked Home Manager then you need to do that
first. Have a look at GitHub's Fork a
repo for instructions on
how to do this.

Once you have a fork of Home Manager you should create a branch starting
at the most recent master branch. Give your branch a reasonably
descriptive name. Commit your changes to this branch and when you are
happy with the result and it fulfills Guidelines then
push the branch to GitHub and create a pull
request.

Assuming your clone is at $HOME/devel/home-manager then you can make
the home-manager command use it by either

  1. overriding the default path by using the -I command line option:

    shell
    $ home-manager -I home-manager=$HOME/devel/home-manager

    or, if using flakes:

    shell
    $ home-manager --override-input home-manager ~/devel/home-manager

    or

  2. changing the default path by ensuring your configuration includes

    nix
    programs.home-manager.enable = true;
programs.home-manager.path = "$HOME/devel/home-manager";

    and running home-manager switch to activate the change.
    Afterwards, home-manager build and home-manager switch will use
    your cloned repository.

The first option is good if you only temporarily want to use your clone.

File: docs/manual/contributing/guidelines.md

Guidelines {#sec-guidelines}

If your contribution satisfy the following rules then there is a good
chance it will be merged without too much trouble. The rules are
enforced by the Home Manager maintainers and to a lesser extent the Home
Manager CI system.

If you are uncertain how these rules affect the change you would like to
make then feel free to start a discussion in the
#home-manager IRC
channel, ideally before you start developing.

Maintain backward compatibility {#sec-guidelines-back-compat}

Your contribution should not cause another user's existing configuration
to break unless there is a very good reason and the change should be
announced to the user through an
assertion
or similar.

Remember that Home Manager is used in many different environments and
you should consider how your change may effect others. For example,

  • Does your change work for people that do not use NixOS? Consider
    other GNU/Linux distributions and macOS.

  • Does your change work for people whose configuration is built on one
    system and deployed on another system?

Keep forward compatibility in mind {#sec-guidelines-forward-compat}

The master branch of Home Manager tracks the unstable channel of
Nixpkgs, which may update package versions at any time. It is therefore
important to consider how a package update may affect your code and try
to reduce the risk of breakage.

The most effective way to reduce this risk is to follow the advice in
Add only valuable options.

Add only valuable options {#sec-guidelines-valuable-options}

When creating a new module it is tempting to include every option
supported by the software. This is strongly discouraged. Providing
many options increases maintenance burden and risk of breakage
considerably. This is why only the most important software
options
should be modeled explicitly. Less important options should be
expressible through an extraConfig escape hatch.

A good rule of thumb for the first implementation of a module is to only
add explicit options for those settings that absolutely must be set for
the software to function correctly. It follows that a module for
software that provides sensible default values for all settings would
require no explicit options at all.

If the software uses a structured configuration format like a JSON,
YAML, INI, TOML, or even a plain list of key/value pairs then consider
using a settings option as described in Nix RFC
42.

These guidelines describe the minimum option design requirements. Before
submitting a module, compare it against the upstream documentation or
source code and verify that the generated files, services, environment
variables, and command line arguments all match the upstream behavior
you intend to expose.

If a module installs a package, try to make the package option nullable,
for example

nix
package = lib.mkPackageOption pkgs "xdg-terminal-exec" { nullable = true; };

This lets users keep installation outside Home Manager, for example via
apt or because the program is built into macOS, while still using the
module for configuration. Keeping the package non-nullable is fine when
the enabled behavior structurally requires the executable or when
package-less support would make the module significantly more complex.

Avoid generating files for empty settings, null packages, or optional
features that are not configured.

If upstream does not use XDG paths by default but supports changing the
configuration location with an environment variable, for example
FOO_HOME, expose a configDir option and use it to respect
home.preferXdgDirectories.

Add relevant tests {#sec-guidelines-add-tests}

If at all possible, make sure to add new tests and expand existing tests
so that your change will keep working in the future. See
Tests for more information about the Home Manager test
suite.

All contributed code must pass the test suite.

Add relevant documentation {#sec-guidelines-module-maintainer}

Many code changes require changing the documentation as well. The
documentation is written in
Nixpkgs-flavoured Markdown.
All text is hosted in Home Manager's Git repository.

The HTML version of the manual containing both the module option
descriptions and the documentation of Home Manager can be generated and
opened by typing the following in a shell within a clone of the Home
Manager Git repository:

shell
$ nix-build -A docs.html
$ xdg-open ./result/share/doc/home-manager/index.html

When you have made changes to a module, it is a good idea to check that
the man page version of the module options looks good:

shell
$ nix-build -A docs.manPages
$ man ./result/share/man/man5/home-configuration.nix.5

Module Auto-importing {#sec-module-auto-importing}

Home Manager automatically imports all modules from the modules/programs/ and
modules/services/ directories. This auto-importing behavior follows these
rules:

  • Nix files: All .nix files in these directories are automatically
    imported
  • Directories: All subdirectories are automatically imported (typically
    containing a default.nix file)
  • Exclusions: Files and directories starting with an underscore (_) are
    excluded from auto-importing

This allows for flexible module organization:

text
modules/programs/
├── git.nix              # Single-file module (imported)
├── firefox/             # Multi-file module (imported)
│   ├── default.nix
│   └── addons.nix
├── _experimental.nix    # Excluded (starts with _)
└── _wip/                # Excluded directory (starts with _)
    └── newfeature.nix

When adding a new module, simply place it in the appropriate directory
(programs/ for user programs, services/ for user services) and it will be
automatically discovered and included in the Home Manager module system.

Add yourself as a module maintainer {#_add_yourself_as_a_module_maintainer}

Every new module must include a named maintainer using the
meta.maintainers attribute. If you are a user of a module that
currently lacks a maintainer then please consider adopting it.

If you are present in the nixpkgs maintainer list then you can use that
entry. If you are not then you can add yourself to
modules/lib/maintainers.nix in the Home Manager project.

As a maintainer you are expected to respond to issues and
pull-requests associated with your module.

Maintainers are encouraged to join the IRC or Matrix channel and
participate when they have opportunity.

Format your code {#sec-guidelines-code-style}

Make sure your code is formatted as described in Code
Style. To maintain consistency throughout the project
you are encouraged to browse through existing code and adopt its style
also in new code.

Format your commit messages {#sec-guidelines-commit-message-style}

Similar to Format your code we encourage a
consistent commit message format as described in
Commits.

Format your news entries {#sec-guidelines-news-style}

If your contribution includes a change that should be communicated to
users of Home Manager then you can add a news entry. The entry must be
formatted as described in News.

When new modules are added a news entry should be included.

News entries and release notes serve different purposes. Release notes
should be updated separately when a change affects users migrating
between stable releases, such as state version default changes, required
migration steps, or broad behavior changes. See
Release Notes and News
for more details.

Use conditional modules and news {#sec-guidelines-conditional-modules}

Home Manager includes a number of modules that are only usable on some
of the supported platforms. The most common example of platform specific
modules are those that define systemd user services, which only works on
Linux systems.

If you add a module that is platform specific then make sure the module
guards platform-specific configuration with an appropriate condition, for
example pkgs.stdenv.hostPlatform.isLinux or
pkgs.stdenv.hostPlatform.isDarwin. Modules in modules/programs/ and
modules/services/ are auto-imported, so the platform condition should live
in the module behavior and in any platform-specific tests rather than in a
separate module discovery call.

Similarly, if you are adding a news entry then it should be shown only
to users that may find it relevant, see News for a
description of conditional news.

Mind the license {#sec-guidelines-licensing}

The Home Manager project is covered by the MIT license and we can only
accept contributions that fall under this license, or are licensed in a
compatible way. When you contribute self written code and documentation
it is assumed that you are doing so under the MIT license.

A potential gotcha with respect to licensing are option descriptions.
Often it is convenient to copy from the upstream software documentation.
When this is done it is important to verify that the license of the
upstream documentation allows redistribution under the terms of the MIT
license.

Commits {#sec-commit-style}

The commits in your pull request should be reasonably self-contained,
that is, each commit should make sense in isolation. In particular, you
will be asked to amend any commit that introduces syntax errors or
similar problems even if they are fixed in a later commit.

Keep commits atomic and separated by concern. For example, a new
maintainer entry should be a separate first commit, and a shared module
should be committed separately from integrations in existing modules.
Pull requests should not include merge commits or fixup commits.

The commit messages should follow the seven
rules, except for
"Capitalize the subject line". We also ask you to include the affected
code component or module in the first line. That is, a commit message
should follow the template

text
{component}: {description}

{long description}

where {component} refers to the code component (or module) your change
affects, {description} is a very brief description of your change, and
{long description} is an optional clarifying description. As a rare
exception, if there is no clear component, or your change affects many
components, then the {component} part is optional. See
example_title for a commit message that fulfills
these requirements.

Example commit {#ex-commit-message}

The commit
69f8e47e9e74c8d3d060ca22e18246b7f7d988ef
contains the commit message

text
starship: allow running in Emacs if vterm is used

    The vterm buffer is backed by libvterm and can handle Starship prompts
    without issues.

which ticks all the boxes necessary to be accepted in Home Manager.

Finally, when adding a new module, say programs/foo.nix, we use the
fixed commit format foo: add module. You can, of course, still include
a long description if you wish.

Code Style {#sec-code-style}

The code in Home Manager is formatted by the treefmt tool
and the formatting is checked in the pull request tests. Run nix fmt or
treefmt (with required formatters which can be found in treefmt.toml in your
$PATH) inside the project repository before submitting your pull request.

Keep lines at a reasonable width, ideally 80 characters or less. This
also applies to string literals.

We prefer lowerCamelCase for variable and attribute names with the
accepted exception of variables directly referencing packages in Nixpkgs
which use a hyphenated style. For example, the Home Manager option
services.gpg-agent.enableSshSupport references the gpg-agent package
in Nixpkgs.

File: docs/manual/contributing/news.md

News {#sec-news}

Home Manager includes a system for presenting news to the user. When
making a change you, therefore, have the option to also include an
associated news entry. In general, a news entry should only be added for
truly noteworthy news. For example, a bug fix or new option does
generally not need a news entry.

Release notes and news entries serve different purposes. A news entry is
shown during Home Manager activation and is useful for day-to-day
communication about noteworthy changes, such as a new module, a new
feature, or a specific deprecation. Release notes are read from the
website documentation and should summarize what users need to know before
or during a stable-release upgrade. See
Release Notes for guidance on changes
that affect stable-release upgrades.

If you do have a change worthy of a news entry then please add one in
news
but you should follow some basic guidelines:

  • Use the included news entry generator to create a news entry file:

    shell
    $ nix run .#create-news-entry

    Alternatively, you can directly use the script:

    shell
    $ nix-shell -A dev --run modules/misc/news/create-news-entry.sh

    This will create a new file inside the modules/misc/news directory
    with some placeholder information that you can edit.

  • The entry condition should be as specific as possible for changes
    affecting existing functionality. For example, if you are changing
    or deprecating a specific option then you could restrict the news to
    those users who actually use this option. Prefer a targeted
    condition over skipping useful news only to avoid notifying
    unaffected users.

  • Wrap the news message so that it will fit in the typical terminal,
    that is, at most 80 characters wide. Ideally a bit less.

  • Unlike commit messages, news will be read without any connection to
    the Home Manager source code. It is therefore important to make the
    message understandable in isolation and to those who do not have
    knowledge of the Home Manager internals. To this end it should be
    written in more descriptive, prose like way.

  • If you refer to an option then write its full attribute path. That
    is, instead of writing

    text
    The option 'foo' has been deprecated, please use 'bar' instead.

    it should read

    text
    The option 'services.myservice.foo' has been deprecated, please
use 'services.myservice.bar' instead.

  • A new module, say foo.nix, should always include a news entry that
    has a message along the lines of

    text
    A new module is available: 'services.foo'.

    Since this news announces newly available functionality, its
    condition should not require config.services.foo.enable; otherwise
    users who may want the new module will not see the news.

    If the module is platform specific, e.g., a service module using
    systemd, then a condition like

    nix
    condition = hostPlatform.isLinux;

    should be added to avoid showing the news on unsupported platforms.
    Use the create-news-entry generator described above to scaffold
    this entry as part of your contribution.

File: docs/manual/contributing/tests.md

Tests {#sec-tests}

Home Manager includes a basic test suite and it is highly recommended to
include at least one test when adding a module. Tests are typically in
the form of "golden tests" where, for example, a generated
configuration file is compared to a known correct file.

It is relatively easy to create tests by modeling the existing tests,
found in the tests project directory.

Writing Basic Tests {#sec-tests-basic}

Home Manager tests use the NMT framework, which provides
a set of assertion functions to verify that modules generate the expected files
and configurations. Tests are written as Nix expressions that define both the
Home Manager configuration and the test assertions.

Test Structure {#sec-tests-structure}

A basic test file structure looks like:

nix
{
  # Home Manager configuration
  programs.myprogram = {
    enable = true;
    settings = {
      option = "value";
    };
  };

  # NMT test script with assertions
  nmt.script = ''
    assertFileExists "home-files/.config/myprogram/config.toml"
    assertFileContent "home-files/.config/myprogram/config.toml" ${./expected-config.toml}
  '';
}

Test Organization {#sec-tests-organization}

Tests are organized in the tests directory structure:

  • tests/modules/programs/myprogram/default.nix - Lists all test cases for the module
  • tests/modules/programs/myprogram/basic-configuration.nix - A basic test case
  • tests/modules/programs/myprogram/expected-config.toml - Expected output file

The default.nix file should list all test cases:

nix
{
  myprogram-basic-configuration = ./basic-configuration.nix;
  myprogram-empty-settings = ./empty-settings.nix;
}

Prefer keeping related assertions in as few test files as practical.
Exercising several cases in one evaluation keeps the test suite cheaper
to evaluate and reduces maintenance burden. Split cases into separate
files when they need incompatible module configuration, platform
conditions, expected assertion failures, or otherwise cannot share one
evaluation.

Common NMT Assertions {#sec-tests-assertions}

NMT provides several assertion functions:

  • assertFileExists "path" - Verify a file was created
  • assertPathNotExists "path" - Verify a file was NOT created
  • assertFileContent "path" expected-file - Compare file contents
  • assertFileRegex "path" "regex" - Check file matches regex

For a full reference to the functions available in test scripts, you can look at NMT's
bash-lib.

Practical Examples {#sec-tests-examples}

Here are some real-world examples of common test patterns:

Testing that a configuration file is generated:

nix
{
  programs.alacritty = {
    enable = true;
    settings.font.size = 12;
  };

  nmt.script = ''
    assertFileExists "home-files/.config/alacritty/alacritty.yml"
    assertFileContains "home-files/.config/alacritty/alacritty.yml" "size: 12"
  '';
}

Testing that no files are created when disabled:

nix
{
  programs.alacritty.enable = false;

  nmt.script = ''
    assertPathNotExists "home-files/.config/alacritty"
  '';
}

Testing exact file content against expected output:

nix
{
  programs.fastfetch = {
    enable = true;
    settings.display.color = "blue";
  };

  nmt.script =
    let
      configFile = "home-files/.config/fastfetch/config.jsonc";
    in
    ''
      assertFileExists "${configFile}"
      assertFileContent "${configFile}" ${./expected-config.jsonc}
    '';
}

Testing multiple conditions in one test:

nix
{
  programs.myprogram = {
    enable = true;
    configFile = "custom.conf";
    extraConfig = "debug = true";
  };

  nmt.script = ''
    assertFileExists "home-files/.config/myprogram/custom.conf"
    assertFileRegex "home-files/.config/myprogram/custom.conf" "debug = true"
    assertFileRegex "home-files/.config/myprogram/custom.conf" "^# Generated by Home Manager"
  '';
}

Platform-Specific Tests {#sec-tests-platform-specific}

When a module is platform-specific (Linux-only or Darwin-only), the test's default.nix
file should use lib.optionalAttrs to conditionally expose tests based on the platform.
This prevents evaluation errors on unsupported platforms during the test suite runs.

Linux-only module tests:

nix
{ lib, pkgs, ... }:

lib.optionalAttrs pkgs.stdenv.hostPlatform.isLinux {
  rofi-valid-config = ./valid-config.nix;
  rofi-custom-theme = ./custom-theme.nix;
}

Darwin-only module tests:

nix
{ lib, pkgs, ... }:

lib.optionalAttrs pkgs.stdenv.hostPlatform.isDarwin {
  sketchybar-basic = ./basic-configuration.nix;
  sketchybar-lua-config = ./lua-config.nix;
}

For cross-platform modules that have packages which need to be stubbed on Darwin,
add the package names to tests/darwinScrublist.nix to prevent build failures
during cross-platform test runs.

On Linux, packages are automatically scrubbed by the test infrastructure,
so tests should normally use the module's default package. Use
test.stubs or config.lib.test.mkStubPackage only when the automatic
scrubbing does not model the behavior that the test needs, such as a
package with additional files or a non-default executable layout.

Using the tests command {#sec-tests-command}

Home Manager provides a convenient tests command for discovering and running tests:

shell
# List all available tests
$ nix run .#tests -- -l

# List tests matching a pattern
$ nix run .#tests -- -l alacritty

# Run all tests matching a pattern
$ nix run .#tests -- alacritty

# Run a specific test
$ nix run .#tests -- test-alacritty-empty-settings

# List integration tests
$ nix run .#tests -- -t -l

# Run all integration tests
$ nix run .#tests -- -t integration-test-

# Interactive test selection (requires fzf)
$ nix run .#tests -- -i

# Pass additional nix build flags
$ nix run .#tests -- alacritty -- --verbose

Integration tests are only exposed on Linux. On other platforms, integration
test discovery may report no matching tests.

Manual test commands {#sec-tests-manual}

For advanced usage or CI environments, you can also run tests manually using nix build commands.

The full Home Manager test suite can be run by executing

shell
$ nix-build --pure --option allow-import-from-derivation false tests -A build.all

in the project root. List all test cases through

shell
$ nix run .#tests -- -l

and run an individual test, for example alacritty-empty-settings,
through

shell
$ nix-build --pure tests --option allow-import-from-derivation false -A build.alacritty-empty-settings

However, those invocations will impurely source the system's Nixpkgs,
and may cause failures. To run against the Nixpkgs from the flake.lock file,
use instead e.g.

shell
$ nix build .#test-all

or

shell
$ nix build .#test-alacritty-empty-settings

Some tests may be marked with enableLegacyIfd, those may be run by run with e.g.

shell
$ nix-build --pure tests --arg enableLegacyIfd true -A build.mytest

File: docs/manual/faq/ca-desrt-dconf.md

Why do I get an error message about `ca.desrt.dconf` or `dconf.service`? {#_why_do_i_get_an_error_message_about_literal_ca_desrt_dconf_literal_or_literal_dconf_service_literal}

You are most likely trying to configure something that uses dconf but
the DBus session is not aware of the dconf service. The full error you
might get is

text
error: GDBus.Error:org.freedesktop.DBus.Error.ServiceUnknown: The name ca.desrt.dconf was not provided by any .service files

or

text
error: GDBus.Error:org.freedesktop.systemd1.NoSuchUnit: Unit dconf.service not found.

The solution on NixOS is to add

nix
programs.dconf.enable = true;

to your system configuration.

File: docs/manual/faq/change-package-module.md

How do I change the package used by a module? {#_how_do_i_change_the_package_used_by_a_module}

By default Home Manager will install the package provided by your chosen
nixpkgs channel but occasionally you might end up needing to change
this package. This can typically be done in two ways.

  1. If the module provides a package option, such as
    programs.beets.package, then this is the recommended way to
    perform the change. For example,

    nix
    programs.beets.package = pkgs.beets.override { pluginOverrides = { beatport.enable = false; }; };

    See Nix pill 17
    for more information on package overrides. Alternatively, if you want
    to use the beets package from Nixpkgs unstable, then a configuration like

    nix
    { pkgs, config, ... }:

let
  pkgsUnstable = import <nixpkgs-unstable> {};
in
{
  programs.beets.package = pkgsUnstable.beets;

  # …
}

    should work OK. With flakes, pass the unstable package set as
    described in
    How do I install packages from Nixpkgs unstable?
    and then use the extra module argument:

    nix
    { pkgsUnstable, ... }:

{
  programs.beets.package = pkgsUnstable.beets;

  # …
}

  2. If no package option is available then you can typically change
    the relevant package using an
    overlay.

    For example, if you want to use the programs.skim module but use
    the skim package from Nixpkgs unstable, then a configuration like

    nix
    { pkgs, config, ... }:

let
  pkgsUnstable = import <nixpkgs-unstable> {};
in

{
  programs.skim.enable = true;

  nixpkgs.overlays = [
    (_final: _prev: {
      skim = pkgsUnstable.skim;
    })
  ];

  # …
}

    should work OK.

    The same Home Manager overlay works in a flake-based standalone
    configuration if pkgsUnstable is passed to the Home Manager
    module:

    nix
    { pkgsUnstable, ... }:

{
  programs.skim.enable = true;

  nixpkgs.overlays = [
    (_final: _prev: {
      skim = pkgsUnstable.skim;
    })
  ];

  # …
}

    This also works when Home Manager is used as a NixOS or nix-darwin
    module without home-manager.useGlobalPkgs = true. If
    home-manager.useGlobalPkgs = true is enabled, Home Manager uses
    the system package set and the nixpkgs.* options inside Home
    Manager are disabled. In that case, put the overlay in the system
    configuration instead, for example:

    nix
    { pkgsUnstable, ... }:

{
  nixpkgs.overlays = [
    (_final: _prev: {
      skim = pkgsUnstable.skim;
    })
  ];
}

    In a flake-based NixOS or nix-darwin configuration, pass
    pkgsUnstable to nixosSystem or darwinSystem with
    specialArgs.

File: docs/manual/faq/collision.md

Why is there a collision error when switching generation? {#_why_is_there_a_collision_error_when_switching_generation}

Home Manager currently installs packages into the user environment,
precisely as if the packages were installed through nix-env --install.
This means that you will get a collision error if your Home Manager
configuration attempts to install a package that you already have
installed manually, that is, packages that shows up when you run
nix-env --query.

For example, imagine you have the hello package installed in your
environment

shell
$ nix-env --query
hello-2.10

and your Home Manager configuration contains

nix
home.packages = [ pkgs.hello ];

Then attempting to switch to this configuration will result in an error
similar to

shell
$ home-manager switch
these derivations will be built:
  /nix/store/xg69wsnd1rp8xgs9qfsjal017nf0ldhm-home-manager-path.drv
[…]
Activating installPackages
replacing old ‘home-manager-path’
installing ‘home-manager-path’
building path(s) ‘/nix/store/b5c0asjz9f06l52l9812w6k39ifr49jj-user-environment’
Wide character in die at /nix/store/64jc9gd2rkbgdb4yjx3nrgc91bpjj5ky-buildenv.pl line 79.
collision between ‘/nix/store/fmwa4axzghz11cnln5absh31nbhs9lq1-home-manager-path/bin/hello’ and ‘/nix/store/c2wyl8b9p4afivpcz8jplc9kis8rj36d-hello-2.10/bin/hello’; use ‘nix-env --set-flag priority NUMBER PKGNAME’ to change the priority of one of the conflicting packages
builder for ‘/nix/store/b37x3s7pzxbasfqhaca5dqbf3pjjw0ip-user-environment.drv’ failed with exit code 2
error: build of ‘/nix/store/b37x3s7pzxbasfqhaca5dqbf3pjjw0ip-user-environment.drv’ failed

The solution is typically to uninstall the package from the environment
using nix-env --uninstall and reattempt the Home Manager generation
switch.

You could also opt to uninstall all of the packages from your profile
with nix-env --uninstall '*'.

File: docs/manual/faq/multiple-users-machines.md

How to set up a configuration for multiple users/machines? {#_how_to_set_up_a_configuration_for_multiple_users_machines}

A typical way to prepare a repository of configurations for multiple
logins and machines is to prepare one "top-level" file for each unique
combination.

For example, if you have two machines, called "kronos" and "rhea" on
which you want to configure your user "jane" then you could create the
files

  • kronos-jane.nix,

  • rhea-jane.nix, and

  • common.nix

in your repository. On the kronos and rhea machines you can then make
~jane/.config/home-manager/home.nix be a symbolic link to the
corresponding file in your configuration repository.

The kronos-jane.nix and rhea-jane.nix files follow the format

nix
{ ... }:

{
  imports = [ ./common.nix ];

  # Various options that are specific for this machine/user.
}

while the common.nix file contains configuration shared across the two
logins. Of course, instead of just a single common.nix file you can
have multiple ones, even one per program or service.

You can get some inspiration from the Post your home-manager home.nix
file!
Reddit thread.

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#dotfiles Browse dotfiles catalog → #nix Browse nix catalog → #nix-dotfiles Browse nix-dotfiles catalog → #nixos Browse nixos catalog → #nixpkgs Browse nixpkgs catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →