2017-01-14 12:04:57 +00:00
|
|
|
Home Manager using Nix
|
|
|
|
|
======================
|
|
|
|
|
|
2023-08-19 16:35:23 +00:00
|
|
|
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.
|
2021-01-08 14:26:58 +00:00
|
|
|
|
2022-05-27 23:29:58 +00:00
|
|
|
Usage
|
|
|
|
|
-----
|
|
|
|
|
|
2023-08-19 16:35:23 +00:00
|
|
|
Before attempting to use Home Manager please read [the warning
|
|
|
|
|
below](#words-of-warning).
|
2017-01-14 12:04:57 +00:00
|
|
|
|
2023-08-19 16:35:23 +00:00
|
|
|
For a systematic overview of Home Manager and its available options, please see:
|
2022-05-27 23:29:58 +00:00
|
|
|
|
2023-08-19 16:35:23 +00:00
|
|
|
- [Home Manager manual][manual]
|
|
|
|
|
- [Home Manager configuration options][configuration options]
|
|
|
|
|
- [3rd party Home Manager option
|
|
|
|
|
search](https://mipmip.github.io/home-manager-option-search/)
|
2020-01-19 15:44:38 +00:00
|
|
|
|
2023-08-19 16:35:23 +00:00
|
|
|
If you would like to contribute to Home Manager, then please have a look at
|
|
|
|
|
["Contributing" in the manual][contributing].
|
2022-01-16 18:01:49 +00:00
|
|
|
|
2023-04-28 09:21:33 +00:00
|
|
|
Releases
|
|
|
|
|
--------
|
|
|
|
|
|
2023-08-19 16:35:23 +00:00
|
|
|
Home Manager is developed against `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-23.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.
|
2023-04-28 09:21:33 +00:00
|
|
|
|
2017-01-14 12:04:57 +00:00
|
|
|
Words of warning
|
|
|
|
|
----------------
|
|
|
|
|
|
2023-08-19 16:35:23 +00:00
|
|
|
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.
|
2017-01-14 12:04:57 +00:00
|
|
|
|
2023-08-19 16:35:23 +00:00
|
|
|
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.
|
2020-06-24 22:10:08 +00:00
|
|
|
|
2023-08-19 16:35:23 +00:00
|
|
|
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 it is about to be
|
|
|
|
|
overwritten was from a previous Home Manager generation or from manual
|
|
|
|
|
configuration.
|
2017-01-14 12:04:57 +00:00
|
|
|
|
2023-08-19 16:35:23 +00:00
|
|
|
Home Manager targets [NixOS][] unstable and NixOS version 23.05 (the current
|
|
|
|
|
stable version), it may or may not work on other Linux distributions and NixOS
|
|
|
|
|
versions.
|
2017-04-01 21:05:36 +00:00
|
|
|
|
2023-08-19 16:35:23 +00:00
|
|
|
Also, the `home-manager` tool does not explicitly support rollbacks at the
|
|
|
|
|
moment so if your home directory gets messed up you'll have to fix it yourself.
|
|
|
|
|
See the [rollbacks][] section for instructions on how to manually perform a
|
|
|
|
|
rollback.
|
2017-01-14 12:04:57 +00:00
|
|
|
|
2023-08-19 16:35:23 +00:00
|
|
|
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.
|
2017-01-14 12:04:57 +00:00
|
|
|
|
2019-03-22 18:10:43 +00:00
|
|
|
Contact
|
|
|
|
|
-------
|
|
|
|
|
|
2023-08-19 16:35:23 +00:00
|
|
|
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.
|
2019-03-22 18:10:43 +00:00
|
|
|
|
2017-01-14 12:04:57 +00:00
|
|
|
Installation
|
|
|
|
|
------------
|
|
|
|
|
|
2021-11-14 22:55:18 +00:00
|
|
|
Home Manager can be used in three primary ways:
|
|
|
|
|
|
2023-08-19 16:35:23 +00:00
|
|
|
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
|
2021-11-14 22:55:18 +00:00
|
|
|
description of this setup.
|
2017-05-06 10:50:32 +00:00
|
|
|
|
2023-08-19 16:35:23 +00:00
|
|
|
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.
|
2022-02-04 15:39:40 +00:00
|
|
|
|
2021-04-29 23:29:39 +00:00
|
|
|
Translations
|
|
|
|
|
------------
|
|
|
|
|
|
|
|
|
|
Home Manager has basic support for internationalization through
|
2023-08-19 16:35:23 +00:00
|
|
|
[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/).
|
2021-04-29 23:29:39 +00:00
|
|
|
|
|
|
|
|
<a href="https://hosted.weblate.org/engage/home-manager/">
|
2023-08-19 16:35:23 +00:00
|
|
|
<img src="https://hosted.weblate.org/widgets/home-manager/-/multi-auto.svg" alt="Translation status" />
|
2021-04-29 23:29:39 +00:00
|
|
|
</a>
|
|
|
|
|
|
2021-11-13 23:59:24 +00:00
|
|
|
License
|
|
|
|
|
-------
|
|
|
|
|
|
|
|
|
|
This project is licensed under the terms of the [MIT license](LICENSE).
|
|
|
|
|
|
2023-08-19 16:35:23 +00:00
|
|
|
[#home-manager]: https://webchat.oftc.net/?channels=home-manager
|
|
|
|
|
[Nix Flakes]: https://nixos.wiki/wiki/Flakes
|
2017-01-14 12:04:57 +00:00
|
|
|
[NixOS]: https://nixos.org/
|
2023-08-19 16:35:23 +00:00
|
|
|
[Nix]: https://nixos.org/explore.html
|
2022-03-20 05:30:06 +00:00
|
|
|
[Nixpkgs]: https://github.com/NixOS/nixpkgs
|
2021-05-29 18:22:40 +00:00
|
|
|
[OFTC]: https://oftc.net/
|
2023-08-19 16:35:23 +00:00
|
|
|
[configuration options]: https://nix-community.github.io/home-manager/options.html
|
|
|
|
|
[contributing]: https://nix-community.github.io/home-manager/#ch-contributing
|
2022-02-04 15:39:40 +00:00
|
|
|
[manual nix flakes]: https://nix-community.github.io/home-manager/index.html#ch-nix-flakes
|
2023-08-19 16:35:23 +00:00
|
|
|
[manual nix-darwin install]: https://nix-community.github.io/home-manager/index.html#sec-install-nix-darwin-module
|
|
|
|
|
[manual nixos install]: https://nix-community.github.io/home-manager/index.html#sec-install-nixos-module
|
|
|
|
|
[manual standalone install]: https://nix-community.github.io/home-manager/index.html#sec-install-standalone
|
|
|
|
|
[manual]: https://nix-community.github.io/home-manager/index.html
|
|
|
|
|
[nix-darwin]: https://github.com/LnL7/nix-darwin
|
2022-04-07 17:22:03 +00:00
|
|
|
[rollbacks]: https://nix-community.github.io/home-manager/index.html#sec-usage-rollbacks
|
