Standalone setup

To prepare an initial Home Manager configuration for your logged in user, you can run the Home Manager init command directly from its flake.

For example, if you are using the unstable version of Nixpkgs or NixOS, then to generate and activate a basic configuration run the command

$ nix run home-manager/master -- init --switch

For Nixpkgs or NixOS version 26.05 run

$ nix run home-manager/release-26.05 -- init --switch

This will generate a flake.nix and a home.nix file in ~/.config/home-manager, creating the directory if it does not exist.

If you need to pass additional values from your flake to home.nix or any imported Home Manager modules, use extraSpecialArgs in the call to home-manager.lib.homeManagerConfiguration:

{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
    home-manager.url = "github:nix-community/home-manager";
  };

  outputs = inputs@{ nixpkgs, home-manager, ... }: {
    homeConfigurations.jdoe = home-manager.lib.homeManagerConfiguration {
      pkgs = nixpkgs.legacyPackages.x86_64-linux;
      extraSpecialArgs = { inherit inputs; };
      modules = [ ./home.nix ];
    };
  };
}

Any attribute in extraSpecialArgs becomes a module argument, so home.nix or imported modules can declare arguments such as { inputs, ... }:.

The lower-level mechanism behind this is _module.args. Set _module.args.<name> from inside a module only when you need to provide a module argument from within the module graph itself. For values that originate outside the module graph, such as flake inputs, prefer extraSpecialArgs.

If you omit the --switch option then the activation will not happen. This is useful if you want to inspect and edit the configuration before activating it.

$ nix run home-manager/$branch -- init
$ # Edit files in ~/.config/home-manager
$ nix run home-manager/$branch -- init --switch

Where $branch is one of master or release-26.05.

After the initial activation has completed successfully then building and activating your flake-based configuration is as simple as

$ home-manager switch

It is possible to override the default configuration directory, if you want. For example,

$ nix run home-manager/$branch -- init --switch ~/hmconf
$ # And after the initial activation.
$ home-manager switch --flake ~/hmconf

::: {.note} The flake inputs are not automatically updated by Home Manager. Update the lock file with nix flake update before switching if you want to use newer input revisions.

If you only want to update specific flake inputs, name them explicitly, for example nix flake update nixpkgs home-manager.

These commands assume that your current directory is the flake. If not, pass the flake path or URI with --flake <flake-uri>. :::

2.8 KiB Raw Blame History

Standalone setup

2.8 KiB

Raw Blame History