pyrox.dev
1.Dd January 1, 1980
2.Dt nixos-install 8
3.Os
4.Sh NAME
5.Nm nixos-install
6.Nd install bootloader and NixOS
7.
8.
9.
10.Sh SYNOPSIS
11.Nm nixos-install
12.Op Fl -verbose | v
13.Op Fl I Ar path
14.Op Fl -root Ar root
15.Op Fl -system Ar path
16.Op Fl -flake Ar flake-uri
17.Op Fl -impure
18.Op Fl -channel Ar channel
19.Op Fl -no-channel-copy
20.Op Fl -no-root-password | -no-root-passwd
21.Op Fl -no-bootloader
22.Op Fl -max-jobs | j Ar number
23.Op Fl -cores Ar number
24.Op Fl -option Ar name value
25.Op Fl -show-trace
26.Op Fl -keep-going
27.Op Fl -help
28.
29.
30.
31.Sh DESCRIPTION
32This command installs NixOS in the file system mounted on
33.Pa /mnt Ns
34, based on the NixOS configuration specified in
35.Pa /mnt/etc/nixos/configuration.nix Ns
36\&. It performs the following steps:
37.
38.Bl -enum
39.It
40It copies Nix and its dependencies to
41.Pa /mnt/nix/store Ns
42\&.
43.
44.It
45It runs Nix in
46.Pa /mnt
47to build the NixOS configuration specified in
48.Pa /mnt/etc/nixos/configuration.nix Ns
49\&.
50.
51.It
52It installs the current channel
53.Dq nixos
54in the target channel profile (unless
55.Fl -no-channel-copy
56is specified).
57.
58.It
59It installs the GRUB boot loader on the device specified in the option
60.Va boot.loader.grub.device
61(unless
62.Fl -no-bootloader
63is specified), and generates a GRUB configuration file that boots into the NixOS
64configuration just installed.
65.
66.It
67It prompts you for a password for the root account (unless
68.Fl -no-root-password
69is specified).
70.El
71.
72.Pp
73This command is idempotent: if it is interrupted or fails due to a temporary
74problem (e.g. a network issue), you can safely re-run it.
75.
76.
77.
78.Sh OPTIONS
79.Bl -tag -width indent
80.It Fl -verbose , v
81Increases the level of verbosity of diagnostic messages printed on standard
82error. For each Nix operation, the information printed on standard output is
83well-defined; any diagnostic information is printed on standard error, never on
84standard output.
85.Pp
86Please note that this option may be specified repeatedly.
87.
88.It Fl -root Ar root
89Defaults to
90.Pa /mnt Ns
91\&. If this option is given, treat the directory
92.Ar root
93as the root of the NixOS installation.
94.
95.It Fl -system Ar path
96If this option is provided,
97.Nm
98will install the specified closure rather than attempt to build one from
99.Pa /mnt/etc/nixos/configuration.nix Ns
100\&.
101.Pp
102The closure must be an appropriately configured NixOS system, with boot loader
103and partition configuration that fits the target host. Such a closure is
104typically obtained with a command such as
105.Ic nix-build -I nixos-config=./configuration.nix '<nixpkgs/nixos>' -A system --no-out-link Ns
106\&.
107.
108.It Fl -flake Ar flake-uri Ns # Ns Ar name
109Build the NixOS system from the specified flake. The flake must contain an
110output named
111.Ql nixosConfigurations. Ns Ar name Ns
112\&.
113.
114.It Fl -channel Ar channel
115If this option is provided, do not copy the current
116.Dq nixos
117channel to the target host. Instead, use the specified derivation.
118.
119.It Fl I Ar Path
120Add a path to the Nix expression search path. This option may be given multiple
121times. See the
122.Ev NIX_PATH
123environment variable for information on the semantics of the Nix search path. Paths added through
124.Fl I
125take precedence over
126.Ev NIX_PATH Ns
127\&.
128.
129.It Fl -max-jobs , j Ar number
130Sets the maximum number of build jobs that Nix will perform in parallel to the
131specified number. The default is 1. A higher value is useful on SMP systems or
132to exploit I/O latency.
133.
134.It Fl -cores Ar N
135Sets the value of the
136.Ev NIX_BUILD_CORES
137environment variable in the invocation of builders. Builders can use this
138variable at their discretion to control the maximum amount of parallelism. For
139instance, in Nixpkgs, if the derivation attribute
140.Va enableParallelBuilding
141is set to true, the builder passes the
142.Fl j Ns Va N
143flag to GNU Make. The value 0 means that the builder should use all available CPU cores in the system.
144.
145.It Fl -option Ar name value
146Set the Nix configuration option
147.Ar name
148to
149.Ar value Ns
150\&.
151.
152.It Fl -show-trace
153Causes Nix to print out a stack trace in case of Nix expression evaluation errors.
154.
155.It Fl -keep-going
156Causes Nix to continue building derivations as far as possible in the face of failed builds.
157.
158.It Fl -help
159Synonym for
160.Ic man nixos-install Ns
161\&.
162.El
163.
164.
165.
166.Sh EXAMPLES
167A typical NixOS installation is done by creating and mounting a file system on
168.Pa /mnt Ns
169, generating a NixOS configuration in
170.Pa /mnt/etc/nixos/configuration.nix Ns
171, and running
172.Nm Ns
173\&. For instance, if we want to install NixOS on an ext4 file system created in
174.Pa /dev/sda1 Ns
175:
176.Bd -literal -offset indent
177$ mkfs.ext4 /dev/sda1
178$ mount /dev/sda1 /mnt
179$ nixos-generate-config --root /mnt
180$ # edit /mnt/etc/nixos/configuration.nix
181$ nixos-install
182$ reboot
183.Ed
184.
185.
186.
187.Sh AUTHORS
188.An -nosplit
189.An Eelco Dolstra
190and
191.An the Nixpkgs/NixOS contributors