Home-manager useUserPackages useGlobalPkgs settings

When I first installed home-manager - i did not think twice about it’s options, but now whenever I see someone’s config I see useUserPackages = true; and useGlobalPkgs = true; set there.

My question is - what difference do they make, and should I change to use them too?

For a reference - i have the whole system config set up with a flake, so in there I use home manager as input, and set home-manager.inputs.nixpkgs.follows = "nixpkgs"
I have no nix channels set up at all.

so If I add:

home-manager.useUserPackages = true;
home-manager.useGlobalPkgs = true;

Will setting this benefit me somehow?
And will I break something by switching those values?


They’re documented here: https://nix-community.github.io/home-manager/nixos-options.html#nixos-opt-home-manager.useGlobalPkgs

They dictate whether NixOS options for configuring nixpkgs should be inherited and whether the NixOS options for user packages should be used instead of home-manager’s own shell init files.

Whether you should use them is up to how much integration with the host NixOS system you want.

Switching useGlobalPkgs on may change what pkgs means in your home-manager config, and disable your nixpkgs config within home-manager. This may break things. For the other setting you’d need to do some serious work to cause breakage, I think.

yes, I read the documentation beforehand, but it did not help me answer my questions )

All I want from home-manager is to provide some programs with some options not configurable without home-manager.

I’ve checked some links i have in .nix-profile/bin and in run/current-system/sw/bin and the ones that exist in both locations seem to be pointing to the same things, so I guess that means that pkgs that home-manager uses is the same exact pkgs that system uses, right? therefore switching useGlobalPkgs to true would not change anything?

1 Like

If you use e.g. NixOS’ nixpkgs.overlays, by default this will modify the contents of NixOS’ pkgs, but not the one in your home-manager config.

home-manager has a similar option, which does the same thing but in a subtly different way. If you use that option, only the pkgs in the home-manager config will have the overlay applied.

This holds true for all other nixpkgs options - things like allowUnfree, etc. Using useGlobalPkgs means disabling the home-manager options, and instead inheriting everything from the NixOS option.

The actual resulting store paths being the same does not mean that the nixpkgs objects you’re pulling from are the same, nor that changing this setting won’t have any effect. Turning it on might for example mean unfree packages that only exist in your home-manager config won’t be allowed anymore.

In fact, most of the time there will not be any differences in the store paths, since you’re ultimately still using the same nixpkgs source, just the evaluation differs. You’d have to forcibly change the nixpkgs version home-manager is using to achieve that.

Anyway, the use cases I can think of are these:

  • useGlobalPkgs
    • You want to use the same overlays and settings for both home-manager and NixOS, and don’t want to have to repeat the configuration.
  • useUserPkgs
    • I’ve never used users.users.<name>.packages, but I believe this side-steps having to use home-manager’s shell configuration to get home-manager packages to install.

If you ever want to deploy your home-manager configuration to non-NixOS systems, using either will cause your NixOS and other system configurations to diverge. You’d end up having to duplicate overlays anyway and you may have issues with shell init that are working on one end but not the other.

If you only use home-manager for NixOS configurations you probably won’t notice a difference, besides maybe having to move some nixpkgs configuration options out of your home-manager config and into your NixOS config once. Your evaluation may also be a tiny bit faster and use less memory because you’re not evaluating nixpkgs twice anymore.


hm, this section of home-manager manual (cannot make a link to exact location on the page, please use search for useUserPackages) only says that packages will be installed not in ~/.nix-profile , but into /etc/profiles (which is also confusing as i don’t currently have that directory, maybe because of a flake system config?)

Could be correct, at which point I believe that ~/.nix-profile is anyway in PATH by default on NixOS, so there’s no reason to prefer one over the other, besides wanting to keep an empty user profile?

Hah, just spotted two infoboxes in the manual that explain the options: https://nix-community.github.io/home-manager/index.html#sec-install-nixos-module

By default packages will be installed to $HOME/.nix-profile but they can be installed to /etc/profiles if

home-manager.useUserPackages = true;

is added to the system configuration. This is necessary if, for example, you wish to use nixos-rebuild build-vm. This option may become the default value in the future.

Fair enough, wonder why it’s necessary in that case, but I guess the user profiles don’t exist under all NixOS build targets. According to the manual this can cause breakage if your env setup scripts were written manually because it changes the path to source for the home env.

By default, Home Manager uses a private pkgs instance that is configured via the home-manager.users..nixpkgs options. To instead use the global pkgs that is configured via the system level nixpkgs options, set

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

So pretty much what I said; however, I’m pretty sure since NixOS 20.09 the second paragraph no longer holds. Otherwise flakes wouldn’t work.


new link is at Home Manager Manual

sorry for the necro-bump