Home Manager: Difference between revisions

Line 1:

[https://github.com/rycee/home-manager Home Manager] is a ~~basic~~ system for managing a user environment using the Nix package manager ~~together with~~ the ~~Nix libraries found~~ in ~~Nixpkgs~~. Before attempting to use Home Manager [https://github.com/rycee/home-manager#words-of-warning please read the warning].

[https://github.com/rycee/home-manager Home Manager] is a system for managing a user environment using the Nix package manager. In other words, Home Manager lets you

* 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.html 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.

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

== Configuration ==

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

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

=== Installation as a user ===

Follow the [https://github.com/nix-community/home-manager#installation official guide]

~~For the latter, add the following to your config. Note: fetchTarball does not check the integrity of the downloaded package.~~

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.

<~~syntaxhighlight lang="nix"~~>

~~imports = [~~

~~...~~

~~(import "${builtins.fetchTarball https:/~~/~~github~~.~~com~~/~~rycee~~/home~~-manager~~/~~archive/master~~.~~tar.gz}/nixos")~~

];

home-manager~~.users.my_username = { ... }~~

</~~syntaxhighlight~~>

~~For~~ a ~~more secure version~~:

=== Usage as a NixOS module ===

Here is a nixos module template you can use:

{ config, pkgs, ... }:

let

home-manager = builtins.fetchGit {

url = "https://github.com/rycee/home-manager.git";

rev = "dd94a849df69fe62fe2cb23a74c2b9330f1189ed"; # ~~CHANGEME~~

rev = "dd94a849df69fe62fe2cb23a74c2b9330f1189ed"; # the commit to fetch

ref = "release-18.09";

ref = "release-18.09"; # the branch to follow: release-xx.yy for stable nixos or master for nixos-unstable.

};

in

Line 28:

Line 32:

];

home-manager.users.my_username = { ... }

home-manager.users.my_username = {

/* Here goes your home-manager config, eg home.packages = [ pkgs.foo ]; */

}

</syntaxhighlight>

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>.

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 ==

=== Using Home Manager as a declarative version of nix-env ===

Nix-env has problematic behavior due to its imperative nature. For example, after installing java 8 with

<code>nix-env -i jdk8</code>, running <code>nix-env --upgrade</code> upgrades java to 10 despite the fact that we initially explicitly requested java 8.

Installing software with Home-manager avoids this problem:

{ pkgs, ...}: {

home.packages = [ pkgs.jdk8 ];

}

</syntaxhighlight>

It is a perfectly valid use case for home-manager to only install software with <code>home.packages</code> without managing dotfiles at all.

=== Usage on non-NixOS Linux ===

~~Builtins.fetch* are built~~-~~in functions~~, ~~in our example~~, ~~we are fetching either a github repository (fetchGit~~)~~, or a tarball (fetchTarball). With fetchGit, we are fetching a specific commit of home-manager (the~~ <~~code~~>~~rev</code> attribute). To get that~~, ~~we can use [https://github~~.~~com/seppeljordan/nix-prefetch-github nix-prefetch-github], which will return a hash (sha256), an owner, a repository, and a commit (rev attribute, that's what we want here)~~. ~~Here, we are pinning 18~~.~~09's release, but you may want to change that to the version of NixOS you're using~~. ~~Use master if you are on unstable~~.

Home Manager has an option to automatically set some environment variables that will ease usage of software installed with nix on non-NixOS linux (fixing local issues, settings XDG_DATA_DIRS, etc.):

~~Finally, in our example, we are fetching home-manager~~/~~nixos folder, that allows us to use more options from home-manager, which are options usable by NixOS only.~~

{ pkgs, ...}: {

targets.genericLinux.enable = true;

}

</syntaxhighlight>

== Managing your dotfiles ==

=== Managing your dotfiles ===

Home Manager has options to configure many common tools. As an example, adding the following

Line 50:

Line 78:

will make Home Manager generate a <code>.config/git/config</code> file for you.

Even for programs for which Home Manager doesn't have configuration options, you can use it to manage your dotfiles, e.g.

Even for programs for which Home Manager doesn't have configuration options, you can use it to manage your dotfiles directly, e.g.

xdg.configFile."i3blocks/config".source = ~~"${my-dotfile-dir}~~/i3blocks.conf"

xdg.configFile."i3blocks/config".source = ./i3blocks.conf;

home.file.".gdbinit".text = ''

set auto-load safe-path /nix/store

'';

</syntaxhighlight>

This will create a symlink <code>$XDG_CONFIG_HOME/i3blocks/config</code>.

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

You have the whole list of the options available in home-manager [https://rycee.gitlab.io/home-manager/options.html here]

Line 68:

Line 99:

You will have to add

dconf.enable = true;

programs.dconf.enable = true;

</syntaxHighlight>

to your system configuration. ( [https://old.reddit.com/r/NixOS/comments/b255k5/home_manager_cannot_set_gnome_themes/ Source] )

@@ Line 1: / Line 1: @@
-[https://github.com/rycee/home-manager Home Manager] is a basic system for managing a user environment using the Nix package manager together with the Nix libraries found in Nixpkgs. Before attempting to use Home Manager [https://github.com/rycee/home-manager#words-of-warning please read the warning].
+[https://github.com/rycee/home-manager Home Manager] is a system for managing a user environment using the Nix package manager. In other words, Home Manager lets you
+* 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.html 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.
+{{Note|Before attempting to use Home Manager [https://github.com/rycee/home-manager#words-of-warning please read the warning].}}
 == Configuration ==
-Home Manager can be configured in <code>~/.config/nixpkgs/home.nix</code> or inside configuration.nix.
+Home Manager can be configured as a user in <code>~/.config/nixpkgs/home.nix</code> or as a module inside configuration.nix.
+=== Installation as a user ===
+Follow the [https://github.com/nix-community/home-manager#installation official guide]
-For the latter, add the following to your config. Note: fetchTarball does not check the integrity of the downloaded package.
+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.
-<syntaxhighlight lang="nix">
-  imports = [
-    ...
-    (import "${builtins.fetchTarball https://github.com/rycee/home-manager/archive/master.tar.gz}/nixos")
-  ];
-  home-manager.users.my_username = { ... }
-</syntaxhighlight>
-For a more secure version:
+=== Usage as a NixOS module ===
+Here is a nixos module template you can use:
 <syntaxhighlight lang="nix">
+{ config, pkgs, ... }:
 let
    home-manager = builtins.fetchGit {
      url = "https://github.com/rycee/home-manager.git";
-     rev = "dd94a849df69fe62fe2cb23a74c2b9330f1189ed"; # CHANGEME
+     rev = "dd94a849df69fe62fe2cb23a74c2b9330f1189ed"; # the commit to fetch
-     ref = "release-18.09";
+     ref = "release-18.09"; # the branch to follow: release-xx.yy for stable nixos or master for nixos-unstable.
    };
 in
@@ Line 28: / Line 32: @@
      ];
-     home-manager.users.my_username = { ... }
+     home-manager.users.my_username = {
+      /* Here goes your home-manager config, eg home.packages = [ pkgs.foo ]; */
+    }
 }
+</syntaxhighlight>
+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>.
+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 ==
+=== Using Home Manager as a declarative version of nix-env ===
+Nix-env has problematic behavior due to its imperative nature. For example, after installing java 8 with
+<code>nix-env -i jdk8</code>, running <code>nix-env --upgrade</code> upgrades java to 10 despite the fact that we initially explicitly requested java 8.
+Installing software with Home-manager avoids this problem:
+<syntaxhighlight lang="nix">
+{ pkgs, ...}: {
+   home.packages = [ pkgs.jdk8 ];
+}
 </syntaxhighlight>
+It is a perfectly valid use case for home-manager to only install software with <code>home.packages</code> without managing dotfiles at all.
+=== Usage on non-NixOS Linux ===
-Builtins.fetch* are built-in functions, in our example, we are fetching either a github repository (fetchGit), or a tarball (fetchTarball). With fetchGit, we are fetching a specific commit of home-manager (the <code>rev</code> attribute). To get that, we can use [https://github.com/seppeljordan/nix-prefetch-github nix-prefetch-github], which will return a hash (sha256), an owner, a repository, and a commit (rev attribute, that's what we want here). Here, we are pinning 18.09's release, but you may want to change that to the version of NixOS you're using. Use master if you are on unstable.
+Home Manager has an option to automatically set some environment variables that will ease usage of software installed with nix on non-NixOS linux (fixing local issues, settings XDG_DATA_DIRS, etc.):
-Finally, in our example, we are fetching home-manager/nixos folder, that allows us to use more options from home-manager, which are options usable by NixOS only.
+<syntaxhighlight lang="nix">
+{ pkgs, ...}: {
+  targets.genericLinux.enable = true;
+}
+</syntaxhighlight>
-== Managing your dotfiles ==
+=== Managing your dotfiles ===
 Home Manager has options to configure many common tools. As an example, adding the following
@@ Line 50: / Line 78: @@
 will make Home Manager generate a <code>.config/git/config</code> file for you.
-Even for programs for which Home Manager doesn't have configuration options, you can use it to manage your dotfiles, e.g.
+Even for programs for which Home Manager doesn't have configuration options, you can use it to manage your dotfiles directly, e.g.
 <syntaxhighlight lang="nix">
-   xdg.configFile."i3blocks/config".source = "${my-dotfile-dir}/i3blocks.conf"
+   xdg.configFile."i3blocks/config".source = ./i3blocks.conf;
+  home.file.".gdbinit".text = ''
+      set auto-load safe-path /nix/store
+  '';
 </syntaxhighlight>
-This will create a symlink <code>$XDG_CONFIG_HOME/i3blocks/config</code>.
+This will create symlink <code>$XDG_CONFIG_HOME/i3blocks/config</code> and <code>~/.gdbinit</code>.
 You have the whole list of the options available in home-manager [https://rycee.gitlab.io/home-manager/options.html here]
@@ Line 68: / Line 99: @@
 You will have to add
 <syntaxHighlight lang=nix>
-dconf.enable = true;
+programs.dconf.enable = true;
 </syntaxHighlight>
 to your system configuration. ( [https://old.reddit.com/r/NixOS/comments/b255k5/home_manager_cannot_set_gnome_themes/ Source] )