pkgs that is configured via
nixpkgs options, sethome-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.
Once installed you can see Chapter 2, Using Home Manager for a more detailed -description of Home Manager and how to use it.
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 that contains 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 +description of Home Manager and how to use it.
Your use of Home Manager is centered around the configuration file,
+which is typically found at ~/.config/home-manager/home.nix in the standard installation
+or ~/.config/home-manager/flake.nix in a Nix flake based installation.
The default configuration used to be placed in ~/.config/nixpkgs¸
+so you may see references to that elsewhere.
+The old directory still works but Home Manager will print a warning message when used.
This configuration file can be built and activated.
Building a configuration produces a directory in the Nix store that contains 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, ... }:
+- In `/home/jdoe/.config/home-manager/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/home-manager/home.nix file containing something like
{ config, pkgs, ... }:
{
# Home Manager needs a bit of information about you and the
@@ -327,13 +331,13 @@ and nixpkgs url to github:Nix
The Home Manager library is exported by the flake under
lib.hm.
-You can use the above flake.nix as a template in ~/.config/nixpkgs by
- $ nix flake new ~/.config/nixpkgs -t github:nix-community/home-manager
+You can use the above flake.nix as a template in ~/.config/home-manager by
+
$ nix flake new ~/.config/home-manager -t github:nix-community/home-manager
Install Home Manager and apply the configuration by
$ nix run <flake-uri>#homeConfigurations.jdoe.activationPackage
Substitute <flake-uri> with the flake URI of the configuration flake.
-If flake.nix resides in ~/.config/nixpkgs,
-<flake-uri> may be ~/.config/nixpkgs
-as a Git tree or path:~/.config/nixpkgs if not.
+If flake.nix resides in ~/.config/home-manager,
+<flake-uri> may be ~/.config/home-manager
+as a Git tree or path:~/.config/home-manager if not.
Since the release 21.05,
building a flake-based configuration is as simple as
$ home-manager switch --flake '<flake-uri>#jdoe'
once home-manager is installed.
Here, jdoe is a configuration specified in the flake file,
@@ -602,7 +606,10 @@ error: build of ‘/nix/store/b37x3s7pzxbasfqhaca5dqbf3pjjw0ip-user-environment.
rhea-jane.nix, and
common.nix
-in your repository. On the kronos and rhea machines you can then make ~jane/.config/nixpkgs/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
{ ... }:
+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
{ ... }:
{
imports = [ ./common.nix ];
diff --git a/release-notes.html b/release-notes.html
index 05ebe9a0..6880df16 100644
--- a/release-notes.html
+++ b/release-notes.html
@@ -2,14 +2,26 @@
Appendix E. Release Notes This section lists the release notes for stable versions of Home Manager and the current unstable version.
This is the current unstable branch and the information in this section is therefore not final.
This release has the following notable changes:
Firefox add-ons are now managed per-profile.
That is, if you are currently having
-
programs.firefox.extensions = [ foo bar ];
in your configuration then you must change it to
programs.firefox.profiles.myprofile.extensions = [ foo bar ];
The state version in this release includes the changes below.
-These changes are only active if the home.stateVersion option is set to "23.05" or later.
-
-The
xsession.windowManager.i3.config.window.titlebar,
-xsession.windowManager.i3.config.floating.titlebar,
-wayland.windowManager.sway.config.window.titlebar,
-wayland.windowManager.sway.config.floating.titlebar, options now default to true which
-is consistent with the default values for those options used by i3 and sway.
-
This is the current unstable branch and the information in this section is therefore not final.
This release has the following notable changes:
+
programs.firefox.extensions = [ foo bar ];
in your configuration then you must change it to
programs.firefox.profiles.myprofile.extensions = [ foo bar ];
+The default configuration location has been changed from
+~/.config/nixpkgs/home.nix to ~/.config/home-manager/home.nix.
+
Similarly, if you are using a Nix flake based setup
+then the default flake file location has changed from
+~/.config/nixpkgs/flake.nix to ~/.config/home-manager/flake.nix.
The old location will continue to work but using it will trigger a warning message.
+We changed the default configuration location to avoid confusion about
+which files belong to Home Manager and which belong to Nixpkgs.
The state version in this release includes the changes below.
+These changes are only active if the home.stateVersion option is set to "23.05" or later.
+The options
+
now default to true which is consistent with the default values
+for those options used by i3 and sway.
This is the current unstable branch and the information in this section is therefore not final.
This release has the following notable changes:
The home.stateVersion option no longer has a default value.
It used to default to “18.09”, which was the Home Manager version
that introduced the option. If your configuration does not explicitly
diff --git a/tools.html b/tools.html
index dc5c2155..44f81f85 100644
--- a/tools.html
+++ b/tools.html
@@ -94,7 +94,9 @@
}
]
Description
This command updates the user environment so that it corresponds to the
- configuration specified in ~/.config/nixpkgs/home.nix or ~/.config/nixpkgs/flake.nix.
+ configuration specified in
+ $XDG_CONFIG_HOME/home-manager/home.nix or
+ $XDG_CONFIG_HOME/home-manager/flake.nix.
All operations using this tool expects a sub-command that indicates the
operation to perform. It must be one of
@@ -157,8 +159,8 @@
remove packages installed through Home Manager from the user profile,
and
- optionally remove all Home Manager generations and make them
- available for immediate garbage collection.
+ remove all Home Manager generations and make them available
+ for immediate garbage collection.