## 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](#words-of-warning).
For a systematic overview of Home Manager and its available options, please see:
- [Home Manager manual][manual]
- [Home Manager configuration options][configuration options]
- [3rd party Home Manager option
search](https://home-manager-options.extranix.com/)
If you would like to contribute to Home Manager, then please have a look at
["Contributing" in the manual][contributing].
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](https://matrix.to/#/#hm:rycee.net), 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][manual standalone install] for instructions on how to perform this
installation.
1. 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][manual nixos install] for a description of
this setup.
1. 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][manual nix-darwin install] for a
description of this setup.
Home Manager provides both the channel-based setup and the flake-based one. See
[Nix Flakes][manual nix flakes] for a description of the flake-based setup.
Translations
------------
Home Manager has basic support for internationalization through
[gettext](https://www.gnu.org/software/gettext/). The translations are hosted by
[Weblate](https://weblate.org/). If you would like to contribute to the
translation effort then start by going to the [Home Manager Weblate
project](https://hosted.weblate.org/engage/home-manager/).
License
-------
This project is licensed under the terms of the [MIT license](LICENSE).
[#home-manager]: https://webchat.oftc.net/?channels=home-manager
[Nix Flakes]: https://wiki.nixos.org/wiki/Flakes
[NixOS]: https://nixos.org/
[Nix]: https://nixos.org/explore.html
[Nixpkgs]: https://github.com/NixOS/nixpkgs
[OFTC]: https://oftc.net/
[configuration options]: https://nix-community.github.io/home-manager/options.xhtml
[contributing]: https://nix-community.github.io/home-manager/#ch-contributing
[manual nix flakes]: https://nix-community.github.io/home-manager/#ch-nix-flakes
[manual nix-darwin install]: https://nix-community.github.io/home-manager/#sec-install-nix-darwin-module
[manual nixos install]: https://nix-community.github.io/home-manager/#sec-install-nixos-module
[manual standalone install]: https://nix-community.github.io/home-manager/#sec-install-standalone
[manual]: https://nix-community.github.io/home-manager/
[nix-darwin]: https://github.com/nix-darwin/nix-darwin
[rollbacks]: https://nix-community.github.io/home-manager/index.xhtml#sec-usage-rollbacks
---
## File: docs/manual/3rd-party/collections.md
# Module Collections {#sec-3rd-party-module-collections}
- [xhmm --- extra Home Manager
modules](https://github.com/schuelermine/xhmm)
A collection of modules maintained by Anselm Schüler.
- [Stylix --- System-wide colorscheming and
typography](https://github.com/danth/stylix/)
Configure your applications to get coherent color scheme and font.
---
## 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](https://help.github.com/articles/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](guidelines.md#sec-guidelines) then
push the branch to GitHub and [create a pull
request](https://help.github.com/articles/creating-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](../nix-flakes/standalone.md#sec-flakes-standalone):
``` 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](https://webchat.oftc.net/?channels=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](https://nixos.org/manual/nixos/stable/index.html#sec-assertions)
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](#sec-guidelines-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](https://github.com/NixOS/rfcs/blob/master/rfcs/0042-config-option.md#valuable-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](https://github.com/NixOS/rfcs/blob/master/rfcs/0042-config-option.md).
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](tests.md#sec-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](https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-markup).
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:
```
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](#sec-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](#sec-guidelines-code-style) we encourage a
consistent commit message format as described in
[Commits](#sec-commit-style).
## 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](news.md#sec-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](release-notes.md#sec-contributing-release-notes) and [News](news.md#sec-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](news.md#sec-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](https://chris.beams.io/posts/git-commit/#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
{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](#ex-commit-message) for a commit message that fulfills
these requirements.
## Example commit {#ex-commit-message}
The commit
[69f8e47e9e74c8d3d060ca22e18246b7f7d988ef](https://github.com/nix-community/home-manager/commit/69f8e47e9e74c8d3d060ca22e18246b7f7d988ef)
contains the commit message
```
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](https://treefmt.com) 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](release-notes.md#sec-contributing-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`](https://github.com/nix-community/home-manager/blob/master/modules/misc/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
The option 'foo' has been deprecated, please use 'bar' instead.
it should read
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
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](https://git.sr.ht/~rycee/nmt/tree/master/item/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
error: GDBus.Error:org.freedesktop.DBus.Error.ServiceUnknown: The name ca.desrt.dconf was not provided by any .service files
or
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](https://nixos.org/guides/nix-pills/nixpkgs-overriding-packages.html)
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 {};
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?](unstable.md#_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](https://nixos.org/nixpkgs/manual/#chap-overlays).
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 {};
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!](https://www.reddit.com/r/NixOS/comments/9bb9h9/post_your_homemanager_homenix_file/)
Reddit thread.