.Dd January 1, 1980

.Os Home Manager

.nh

.ad l

.cflags 4 /

.Nm home-manager

.Nd reconfigure a user environment

.Nm home-manager

.Bro

.Cm build

.Cm | init Op Fl -switch Ar dir

.Cm | instantiate

.Cm | edit

.Cm | expire-generations Ar timestamp

.Cm | generations

.Cm | help

.Cm | news

.Cm | option Ar option.name

.Cm | packages

.Cm | remove-generations Ar ID \&...

.Cm | uninstall

.Brc

.Op Fl A Ar attrPath

.Op Fl I Ar path

.Op Fl -flake Ar flake-uri

.Op Fl b Ar ext

.Op Bro Fl f | Fl -file Brc Ar path

.Op Bro Fl h | Fl -help Brc

.Op Fl -version

.Op Bro Fl n | Fl -dry-run Brc

.Op Fl -option Ar name Ar value

.Op Fl -cores Ar number

.Op Bro Fl j | Fl -max-jobs Brc Ar number

.Op Fl -option

.Op Fl -impure

.Op Fl -keep-failed

.Op Fl -keep-going

.Op Bro Fl L | Fl -print-build-logs Brc

.Op Fl -show-trace

.Op Fl -(no-)substitute

.Op Fl -no-out-link

.Op Fl -refresh

.Op Bro Fl v | Fl -verbose Brc

.Pp

This command updates the user environment so that it corresponds to the configuration specified in

$XDG_CONFIG_HOME/home-manager/home.nix

or

$XDG_CONFIG_HOME/home-manager/flake.nix.

.Pp

All operations using this tool expects a sub-command that indicates the operation to perform. It must be one of

.Pp

.Bl -tag -width Ds

.It Cm build

.RS 4

Build configuration into a result directory.

.RE

.It Cm init Op Fl -switch Op Ar dir

.RS 14

Generates an initial home.nix file for the current user. If Nix flakes are

enabled, then this command also generates a flake.nix file.

.sp

If a path

.Ar dir

is given then the configuration will be generated in that directory. Otherwise, the configuration will be generated in

~/.config/home-manager. The output directory will be created if it does not exist.

.sp

If the

.Fl -switch

option is given, then the generated configuration is activated.

.sp

Note, this command will not overwrite any existing files. It is therefore safe to initialize a configuration, edit it, and then re-run the

.Cm init

command with

.Fl -switch

enabled to activate the configuration.

.RE

.Pp

.It Cm instantiate

.RS 15

Instantiate the configuration and print the resulting derivation\&.

.RE

.Pp

.It Cm edit

.RS 16

Open the home configuration using the editor indicated by \fBVISUAL\fR or \fBEDITOR\fR\&.

.RE

.Pp

.It Cm expire-generations Ar timestamp

.RS 4

Remove generations older than

.Ar timestamp

where

.Ar timestamp

is interpreted as in the

.Fl d

argument of the

\fBdate\fR(1)

tool. For example

-30 days or 2018-01-01.

.RE

.PP

.It Cm generations

.RS 4

List all home environment generations\&.

.RE

.Pp

.It Cm help

.RS 4

Print tool help.

.RE

.Pp

.It Cm news

.RS 4

Show news entries in a pager.

.RE

.PP

.It Cm option Ar option.name

.RS 4

Inspect the given option name in the home configuration, like

\fBnixos-option\fR(8)\&.

.RE

.Pp

.It Cm packages

.RS 4

List all packages installed in home-manager-path.

.RE

.Pp

.It Cm remove-generations Ar ID \&...

.RS 4

Remove indicated generations. Use the

.Cm generations

sub-command to find suitable generation numbers.

.RE

.Pp

.It Cm switch

.RS 4

Build and activate the configuration\&.

.RE

.Pp

.It Cm uninstall

.RS 4

Remove Home Manager from the user environment\&. This will

.sp

.RE

.RS 4

.Bl -bullet

.It

remove all managed files from the home directory,

.RE

.sp

.RS 4

.It

remove packages installed through Home Manager from the user profile, and

.RE

.sp

.RS 4

.It

remove all Home Manager generations and make them available for immediate garbage collection\&.

.RE

.El

.sp

.RE

.El

.Pp

The tool accepts the options

.Pp

.Bl -tag -width Ds

.It Cm Fl A Ar attrPath

.RS 4

Optional attribute that selects a configuration expression in the configuration file. That is, if

home.nix contains

.sp

.if n \{\

.RS 4

.\}

.nf

{

joe\-at\-work = {pkgs, \&.\&.\&.}: { home\&.packages = [ pkgs\&.fortune ]; };

joe\-at\-home = {pkgs, \&.\&.\&.}: { home\&.packages = [ pkgs\&.cowsay ]; };

}

.fi

.if n \{\

.RE

.\}

.sp

then the command

\fBhome\-manager switch \-A joe\-at\-work\fR

will activate the profile containing the fortune program\&.

.RE

.PP

.It Cm Fl I Ar path

.RS 4

Add a path to the Nix expression search path. For example, to build a Home Manager profile using a specific Nixpkgs run

.Cm home-manager Fl I Ar nixpkgs=/absolute/path/to/nixpkgs build.

By default

.Ar <nixpkgs>

is used.

.RE

.Pp

.It Cm Fl -flake Ar flake-uri[#name]

.RS 4

Build Home Manager configuration from the flake, which must contain the output homeConfigurations.name. If no name is specified it will first try username@hostname and then username.

.RE

.Pp

.It Cm Fl b Ar extension

.RS 4

Enable automatic resolution of collisions between unmanaged and managed files\&. The name of the original file will be suffixed by the given extension\&. For example,

.sp

.if n \{\

.RS 4

.\}

.nf

$ \fBhome\-manager \-b bck switch\fR

.fi

.if n \{\

.RE

.\}

.sp

will cause a colliding file

~/\&.config/foo\&.conf

to be moved to

~/\&.config/foo\&.conf\&.bck\&.

.RE

.Pp

.It Cm Fl f Ar path, Fl -file Ar path

.RS 4

Indicates the path to the Home Manager configuration file. If not given,

$XDG_CONFIG_HOME/home-manager/home.nix

is used.

.RE

.Pp

.It Cm Fl h, Fl -help

.RS 4

Prints usage information for the

tool.

.RE

.Pp

.It Cm Fl -version

.RS 4

Prints the version number of the

tool.

.RE

.Pp

.It Cm Fl n, Fl -dry-run

.RS 4

Perform a dry-run of the given operation, only prints what actions would be taken.

.RE

.Pp

.It Cm Fl -option Ar name Ar value

.RS 4

Passed on to

\fBnix-build\fR(1)\&.

.RE

.Pp

.It Cm Fl -cores Ar number

.RS 4

Passed on to

\fBnix-build\fR(1)\&.

.RE

.Pp

.It Cm Fl j Ar number, Fl -max-jobs Ar number

.RS 4

Passed on to

\fBnix-build\fR(1)\&.

.RE

.Pp

.It Cm Fl -debug

.RS 4

Passed on to

\fBnix-build\fR(1)\&.

.RE

.Pp

.It Cm Fl -impure

.RS 4

Passed on to

\fBnix-build\fR(1)\&.

.RE

.Pp

.It Cm Fl -keep-failed

.RS 4

Passed on to

\fBnix-build\fR(1)\&.

.RE

.Pp

.It Cm Fl -keep-going

.RS 4

Passed on to

\fBnix-build\fR(1)\&.

.RE

.Pp

.It Cm Fl L, Fl -print-build-logs

.RS 4

Passed on to

\fBnix build\fR()

when building from a flake\&.

.RE

.Pp

.It Cm Fl -show-trace

.RS 4

Passed on to

\fBnix-build\fR(1)\&.

.RE

.Pp

.It Cm Fl -(no-)substitute

.RS 4

Passed on to

\fBnix-build\fR(1)\&.

.RE

.Pp

.It Cm Fl -no-out-link

.RS 4

Passed on to

\fBnix-build\fR(1)

when running

\fBhome\-manager build\fR\&.

.RE

.Pp

.It Cm Fl -refresh

.RS 4

Passed on to

\fBnix-build\fR(1)

.RE

.Pp

.It Cm Fl v, Fl -verbose

.RS 4

Activates verbose output\&.

.RE

.El

.Pp

$XDG_DATA_HOME/home\-manager/news\-read\-ids

.RS 4

Identifiers of news items that have been shown\&. Can be deleted to reset the read news indicator\&.

.RE

.Pp

Please report any bugs on the

\m[blue]\fBproject issue tracker\fR\m[]\&.

.Pp

\fBhome-configuration.nix\fR(5)

.Pp

\fBHome Manager contributors\fR

.RS 4

Author.

.RE

.br

Copyright \(co 2017\(en2022 Home Manager contributors

.br