Home Manager: Difference between revisions

(16 intermediate revisions by 12 users not shown)

Line 2:

* install software declaratively in your user profile, rather than using nix-env

* manage dotfiles in the home directory of your user.

Home Manager has many [https://nix-community.github.io/home-manager/options.xhtml options], which can look daunting at first, but most of those options only boil down to creating some ~~dotfile~~ and installing some software in a way similar way to nix-env.

Home Manager has many [https://nix-community.github.io/home-manager/options.xhtml options], which can look daunting at first, but most of those options only boil down to creating some dotfiles and installing some software in a way similar way to nix-env.

{{Note|Before attempting to use Home Manager [https://github.com/rycee/home-manager#words-of-warning please read the warning].}}

Line 8:

== Configuration ==

Home Manager can be configured as a user in <code>~/.config/~~nixpkgs~~/home.nix</code> or as a module inside configuration.nix.

Home Manager can be configured as a user in <code>~/.config/home-manager/home.nix</code> or as a module inside configuration.nix.

=== Installation as a user ===

Line 14:

Follow the [https://nix-community.github.io/home-manager/index.xhtml#ch-installation official guide]

Your configuration is stored in <code>~/.config/~~nixpkgs~~/home.nix</code>. Each time you modify it, rerun <code>home-manager switch</code> for changes to have effect.

Your configuration is stored in <code>~/.config/home-manager/home.nix</code>. Each time you modify it, rerun <code>home-manager switch</code> for changes to have effect.

Note that to work correctly, home-manager needs your shell to source <code>~/.nix-profile/etc/profile.d/hm-session-vars.sh</code>. The most convenient way to do so is to have home-manager manage your whole shell configuration, eg <code>programs.bash.enable = true;</code> or <code>programs.zsh.enable = true;</code>. But in this case your whole bashrc is managed with Home Manager: the years of customization you accumulated in your former .bashrc must be migrated to Home Manager options, which may take some time. The quick and dirty way to do the migration is to move your bashrc to some other location and source it from Home Manager:

Line 50:

It can either be incorporated in <code>/etc/nixos/configuration.nix</code> or be placed in a standalone file and imported in configuration.nix: <code>imports = [ ./thefile.nix ]</code>.

~~To use it inside nixosConfigurations~~ in a Flake, ~~put~~ home-manager ~~in your~~ inputs ~~and in your~~ configuration ~~modules import <code>~~home-manager.nixosModules.home-manager</~~code~~>, ~~then you can use it as above~~.

Whenever you change you home-manager configuration, you must rerun <code>nixos-rebuild switch</code>. With this method, changing the configuration of an unprivileged user requires to run a command as root.

=== Usage as a NixOS module in a Flake ===

Here is the skeleton of how to add Home Manager as a module to your system(s) via your [[Flakes|flake]]:

{

inputs = {

nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.11";

home-manager = {

url = "github:nix-community/home-manager/release-24.11";

inputs.nixpkgs.follows = "nixpkgs";

};

outputs = { self, nixpkgs, home-manager, ... }@inputs:

nixosConfigurations.exampleMachine = nixosConfiguration "exampleMachine"

system = "x86_64-linux";

modules = [

./configuration.nix

home-manager.nixosModules.home-manager

{

home-manager.useGlobalPkgs = true;

home-manager.useUserPackages = true;

home-manager.users.your-username = import ./home.nix;

};

];

};

}

</syntaxhighlight>

Here's an example of home manager configuration in ./home.nix

{ config, pkgs, ... }:

~~Whenever you change~~ you home-~~manager~~ configuration~~, you must rerun <code>nixos~~-~~rebuild switch~~</~~code~~>. ~~With~~ this ~~method, changing~~ the ~~configuration of an unprivileged user requires~~ to ~~run~~ a ~~command~~ as root.

{

# Home Manager needs a bit of information about you and the

# paths it should manage.

home.username = "your-username";

home.homeDirectory = "/home/your-username";

# 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 = "24.11";

# Let Home Manager install and manage itself.

programs.home-manager.enable = true;

}

</syntaxhighlight>

Of course you'll probably want to keep more stuff in there than just a state version, but the state version is required.

The downside to doing it this way over the User config is that you have to do a full system rebuild; the home manager config is part of the full system, and so must be built as root or at least a trusted user.

== Usage ==

Line 100:

Line 155:

This will create symlink <code>$XDG_CONFIG_HOME/i3blocks/config</code> and <code>~/.gdbinit</code>.

{{Note|In both ways ("source" and "text"), the symlink points to a target in /nix/store. The difference is that, "source" would overwrite the content of the dot file, while "text" would add the text to the dot file that may also be affected in other places.}}

You have the whole list of the options available in home-manager [https://nix-community.github.io/home-manager/options.xhtml here]

Line 107:

Line 164:

* [https://github.com/yrashk/nix-home/blob/master/home.nix Yurii Rashkovskii's home.nix]

* [https://git.sr.ht/~ben/config bsima's configs]

* [https://github.com/~~srid~~/nixos-~~config srid~~'s config, with flakes]

* [https://github.com/drupol/nixos-x260 drupol's config, with flakes]

== FAQ ==

Line 113:

Line 170:

=== I cannot set GNOME or Gtk themes via home-manager ===

If you get [https://nix-community.github.io/home-manager/index.~~html~~#_why_do_i_get_an_error_message_about_literal_ca_desrt_dconf_literal_or_literal_dconf_service_literal an error about {{ic|ca.desrt.conf}} or {{ic|dconf.service}}] on NixOS, add

If you get [https://nix-community.github.io/home-manager/index.xhtml#_why_do_i_get_an_error_message_about_literal_ca_desrt_dconf_literal_or_literal_dconf_service_literal an error about {{ic|ca.desrt.conf}} or {{ic|dconf.service}}] on NixOS, add

programs.dconf.enable = true;

Line 149:

Line 206:

* [[Wrappers vs. Dotfiles]] shows how (per-user) wrapper scripts can be used in place of dotfiles in the user's home directory

* [https://github.com/viperML/wrapper-manager wrapper-manager], an implementation of the idea above using the module system

== See also ==

Line 154:

Line 212:

* Starting from a machine with a minimal freshly installed NixOS ISO (KDE Plasma version), this video outlines the basics of using Home Manager as of 2021: [http://enia.cc/r/wilt-nixos-install-home-manager Wil T's "''NixOS Installation Guide''" (Home Manager section starts at 27:22)]

[[Category:Software]]

[[Category:Software]][[Category:Home Manager]]

@@ Line 2: / Line 2: @@
 * install software declaratively in your user profile, rather than using nix-env
 * manage dotfiles in the home directory of your user.
-Home Manager has many [https://nix-community.github.io/home-manager/options.xhtml options], which can look daunting at first, but most of those options only boil down to creating some dotfile and installing some software in a way similar way to nix-env.
+Home Manager has many [https://nix-community.github.io/home-manager/options.xhtml options], which can look daunting at first, but most of those options only boil down to creating some dotfiles and installing some software in a way similar way to nix-env.
 {{Note|Before attempting to use Home Manager [https://github.com/rycee/home-manager#words-of-warning please read the warning].}}
@@ Line 8: / Line 8: @@
 == Configuration ==
-Home Manager can be configured as a user in <code>~/.config/nixpkgs/home.nix</code> or as a module inside configuration.nix.
+Home Manager can be configured as a user in <code>~/.config/home-manager/home.nix</code> or as a module inside configuration.nix.
 === Installation as a user ===
@@ Line 14: / Line 14: @@
 Follow the [https://nix-community.github.io/home-manager/index.xhtml#ch-installation official guide]
-Your configuration is stored in <code>~/.config/nixpkgs/home.nix</code>. Each time you modify it, rerun <code>home-manager switch</code> for changes to have effect.
+Your configuration is stored in <code>~/.config/home-manager/home.nix</code>. Each time you modify it, rerun <code>home-manager switch</code> for changes to have effect.
 Note that to work correctly, home-manager needs your shell to source <code>~/.nix-profile/etc/profile.d/hm-session-vars.sh</code>. The most convenient way to do so is to have home-manager manage your whole shell configuration, eg <code>programs.bash.enable = true;</code> or <code>programs.zsh.enable = true;</code>. But in this case your whole bashrc is managed with Home Manager: the years of customization you accumulated in your former .bashrc must be migrated to Home Manager options, which may take some time. The quick and dirty way to do the migration is to move your bashrc to some other location and source it from Home Manager:
@@ Line 50: / Line 50: @@
 It can either be incorporated in <code>/etc/nixos/configuration.nix</code> or be placed in a standalone file and imported in configuration.nix: <code>imports = [ ./thefile.nix ]</code>.
-To use it inside nixosConfigurations in a Flake, put home-manager in your inputs and in your configuration modules import <code>home-manager.nixosModules.home-manager</code>, then you can use it as above.
+Whenever you change you home-manager configuration, you must rerun <code>nixos-rebuild switch</code>. With this method, changing the configuration of an unprivileged user requires to run a command as root.
+=== Usage as a NixOS module in a Flake ===
+Here is the skeleton of how to add Home Manager as a module to your system(s) via your [[Flakes|flake]]:
+<syntaxhighlight lang="nix">
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.11";
+    home-manager = {
+      url = "github:nix-community/home-manager/release-24.11";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+  };
+  outputs = { self, nixpkgs, home-manager, ... }@inputs:
+    nixosConfigurations.exampleMachine = nixosConfiguration "exampleMachine"
+      system = "x86_64-linux";
+      modules = [
+          ./configuration.nix
+          home-manager.nixosModules.home-manager
+          {
+            home-manager.useGlobalPkgs = true;
+            home-manager.useUserPackages = true;
+            home-manager.users.your-username = import ./home.nix;
+        };
+      ];
+    };
+  };
+}
+</syntaxhighlight>
+Here's an example of home manager configuration in ./home.nix
+<syntaxhighlight lang="nix">
+{ config, pkgs, ... }:
-Whenever you change you home-manager configuration, you must rerun <code>nixos-rebuild switch</code>. With this method, changing the configuration of an unprivileged user requires to run a command as root.
+{
+  # Home Manager needs a bit of information about you and the
+  # paths it should manage.
+  home.username = "your-username";
+  home.homeDirectory = "/home/your-username";
+  # 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 = "24.11";
+  # Let Home Manager install and manage itself.
+  programs.home-manager.enable = true;
+}
+</syntaxhighlight>
+Of course you'll probably want to keep more stuff in there than just a state version, but the state version is required.
+The downside to doing it this way over the User config is that you have to do a full system rebuild; the home manager config is part of the full system, and so must be built as root or at least a trusted user.
 == Usage ==
@@ Line 100: / Line 155: @@
 This will create symlink <code>$XDG_CONFIG_HOME/i3blocks/config</code> and <code>~/.gdbinit</code>.
+{{Note|In both ways ("source" and "text"), the symlink points to a target in /nix/store. The difference is that, "source" would overwrite the content of the dot file, while "text" would add the text to the dot file that may also be affected in other places.}}
 You have the whole list of the options available in home-manager [https://nix-community.github.io/home-manager/options.xhtml here]
@@ Line 107: / Line 164: @@
 * [https://github.com/yrashk/nix-home/blob/master/home.nix Yurii Rashkovskii's home.nix]
 * [https://git.sr.ht/~ben/config bsima's configs]
-* [https://github.com/srid/nixos-config srid's config, with flakes]
+* [https://github.com/drupol/nixos-x260 drupol's config, with flakes]
 == FAQ ==
@@ Line 113: / Line 170: @@
 === I cannot set GNOME or Gtk themes via home-manager ===
-If you get [https://nix-community.github.io/home-manager/index.html#_why_do_i_get_an_error_message_about_literal_ca_desrt_dconf_literal_or_literal_dconf_service_literal an error about {{ic|ca.desrt.conf}} or {{ic|dconf.service}}] on NixOS, add
+If you get [https://nix-community.github.io/home-manager/index.xhtml#_why_do_i_get_an_error_message_about_literal_ca_desrt_dconf_literal_or_literal_dconf_service_literal an error about {{ic|ca.desrt.conf}} or {{ic|dconf.service}}] on NixOS, add
 <syntaxHighlight lang=nix>
 programs.dconf.enable = true;
@@ Line 149: / Line 206: @@
 * [[Wrappers vs. Dotfiles]] shows how (per-user) wrapper scripts can be used in place of dotfiles in the user's home directory
+* [https://github.com/viperML/wrapper-manager wrapper-manager], an implementation of the idea above using the module system
 == See also ==
@@ Line 154: / Line 212: @@
 * Starting from a machine with a minimal freshly installed NixOS ISO (KDE Plasma version), this video outlines the basics of using Home Manager as of 2021: [http://enia.cc/r/wilt-nixos-install-home-manager Wil T's "''NixOS Installation Guide''" (Home Manager section starts at 27:22)]
-[[Category:Software]]
+[[Category:Software]][[Category:Home Manager]]