pyrox.dev
1<refentry xmlns="http://docbook.org/ns/docbook"
2 xmlns:xlink="http://www.w3.org/1999/xlink"
3 xmlns:xi="http://www.w3.org/2001/XInclude">
4 <refmeta>
5 <refentrytitle><command>nixos-install</command>
6 </refentrytitle><manvolnum>8</manvolnum>
7 <refmiscinfo class="source">NixOS</refmiscinfo>
8<!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->
9 </refmeta>
10 <refnamediv>
11 <refname><command>nixos-install</command></refname>
12 <refpurpose>install bootloader and NixOS</refpurpose>
13 </refnamediv>
14 <refsynopsisdiv>
15 <cmdsynopsis>
16 <command>nixos-install</command>
17 <arg>
18 <group choice='req'>
19 <arg choice='plain'>
20 <option>--verbose</option>
21 </arg>
22 <arg choice='plain'>
23 <option>-v</option>
24 </arg>
25 </group>
26 </arg>
27 <arg>
28 <arg choice='plain'>
29 <option>-I</option>
30 </arg>
31 <replaceable>path</replaceable>
32 </arg>
33
34 <arg>
35 <arg choice='plain'>
36 <option>--root</option>
37 </arg>
38 <replaceable>root</replaceable>
39 </arg>
40
41 <arg>
42 <arg choice='plain'>
43 <option>--system</option>
44 </arg>
45 <replaceable>path</replaceable>
46 </arg>
47
48 <arg>
49 <option>--flake</option> <replaceable>flake-uri</replaceable>
50 </arg>
51
52 <arg>
53 <group choice='req'>
54 <arg choice='plain'><option>--impure</option></arg>
55 </group>
56 </arg>
57
58 <arg>
59 <arg choice='plain'>
60 <option>--channel</option>
61 </arg>
62 <replaceable>channel</replaceable>
63 </arg>
64
65 <arg>
66 <arg choice='plain'>
67 <option>--no-channel-copy</option>
68 </arg>
69 </arg>
70
71 <arg>
72 <group choice='req'>
73 <arg choice='plain'>
74 <option>--no-root-password</option>
75 </arg>
76 <arg choice='plain'>
77 <option>--no-root-passwd</option>
78 </arg>
79 </group>
80 </arg>
81
82 <arg>
83 <arg choice='plain'>
84 <option>--no-bootloader</option>
85 </arg>
86 </arg>
87
88 <arg>
89 <group choice='req'>
90 <arg choice='plain'>
91 <option>--max-jobs</option>
92 </arg>
93
94 <arg choice='plain'>
95 <option>-j</option>
96 </arg>
97 </group> <replaceable>number</replaceable>
98 </arg>
99
100 <arg>
101 <option>--cores</option> <replaceable>number</replaceable>
102 </arg>
103
104 <arg>
105 <option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable>
106 </arg>
107
108 <arg>
109 <arg choice='plain'>
110 <option>--show-trace</option>
111 </arg>
112 </arg>
113
114 <arg>
115 <arg choice='plain'>
116 <option>--keep-going</option>
117 </arg>
118 </arg>
119
120 <arg>
121 <arg choice='plain'>
122 <option>--help</option>
123 </arg>
124 </arg>
125 </cmdsynopsis>
126 </refsynopsisdiv>
127 <refsection>
128 <title>Description</title>
129 <para>
130 This command installs NixOS in the file system mounted on
131 <filename>/mnt</filename>, based on the NixOS configuration specified in
132 <filename>/mnt/etc/nixos/configuration.nix</filename>. It performs the
133 following steps:
134 <itemizedlist>
135 <listitem>
136 <para>
137 It copies Nix and its dependencies to
138 <filename>/mnt/nix/store</filename>.
139 </para>
140 </listitem>
141 <listitem>
142 <para>
143 It runs Nix in <filename>/mnt</filename> to build the NixOS configuration
144 specified in <filename>/mnt/etc/nixos/configuration.nix</filename>.
145 </para>
146 </listitem>
147 <listitem>
148 <para>
149 It installs the current channel <quote>nixos</quote> in the target channel
150 profile (unless <option>--no-channel-copy</option> is specified).
151 </para>
152 </listitem>
153 <listitem>
154 <para>
155 It installs the GRUB boot loader on the device specified in the option
156 <option>boot.loader.grub.device</option> (unless
157 <option>--no-bootloader</option> is specified), and generates a GRUB
158 configuration file that boots into the NixOS configuration just
159 installed.
160 </para>
161 </listitem>
162 <listitem>
163 <para>
164 It prompts you for a password for the root account (unless
165 <option>--no-root-password</option> is specified).
166 </para>
167 </listitem>
168 </itemizedlist>
169 </para>
170 <para>
171 This command is idempotent: if it is interrupted or fails due to a temporary
172 problem (e.g. a network issue), you can safely re-run it.
173 </para>
174 </refsection>
175 <refsection>
176 <title>Options</title>
177 <para>
178 This command accepts the following options:
179 </para>
180 <variablelist>
181 <varlistentry>
182 <term><option>--verbose</option> / <option>-v</option></term>
183 <listitem>
184 <para>Increases the level of verbosity of diagnostic messages
185 printed on standard error. For each Nix operation, the information
186 printed on standard output is well-defined; any diagnostic
187 information is printed on standard error, never on standard
188 output.</para>
189 <para>Please note that this option may be specified repeatedly.</para>
190 </listitem>
191 </varlistentry>
192 <varlistentry>
193 <term>
194 <option>--root</option>
195 </term>
196 <listitem>
197 <para>
198 Defaults to <filename>/mnt</filename>. If this option is given, treat the
199 directory <replaceable>root</replaceable> as the root of the NixOS
200 installation.
201 </para>
202 </listitem>
203 </varlistentry>
204 <varlistentry>
205 <term>
206 <option>--system</option>
207 </term>
208 <listitem>
209 <para>
210 If this option is provided, <command>nixos-install</command> will install
211 the specified closure rather than attempt to build one from
212 <filename>/mnt/etc/nixos/configuration.nix</filename>.
213 </para>
214 <para>
215 The closure must be an appropriately configured NixOS system, with boot
216 loader and partition configuration that fits the target host. Such a
217 closure is typically obtained with a command such as <command>nix-build
218 -I nixos-config=./configuration.nix '<nixpkgs/nixos>' -A system
219 --no-out-link</command>
220 </para>
221 </listitem>
222 </varlistentry>
223 <varlistentry>
224 <term>
225 <option>--flake</option> <replaceable>flake-uri</replaceable>#<replaceable>name</replaceable>
226 </term>
227 <listitem>
228 <para>
229 Build the NixOS system from the specified flake.
230 The flake must contain an output named
231 <literal>nixosConfigurations.<replaceable>name</replaceable></literal>.
232 </para>
233 </listitem>
234 </varlistentry>
235 <varlistentry>
236 <term>
237 <option>--channel</option>
238 </term>
239 <listitem>
240 <para>
241 If this option is provided, do not copy the current
242 <quote>nixos</quote> channel to the target host. Instead, use the
243 specified derivation.
244 </para>
245 </listitem>
246 </varlistentry>
247 <varlistentry>
248 <term>
249 <option>-I</option>
250 </term>
251 <listitem>
252 <para>
253 Add a path to the Nix expression search path. This option may be given
254 multiple times. See the NIX_PATH environment variable for information on
255 the semantics of the Nix search path. Paths added through
256 <replaceable>-I</replaceable> take precedence over NIX_PATH.
257 </para>
258 </listitem>
259 </varlistentry>
260 <varlistentry>
261 <term>
262 <option>--max-jobs</option>
263 </term>
264 <term>
265 <option>-j</option>
266 </term>
267 <listitem>
268 <para>
269 Sets the maximum number of build jobs that Nix will perform in parallel
270 to the specified number. The default is <literal>1</literal>. A higher
271 value is useful on SMP systems or to exploit I/O latency.
272 </para>
273 </listitem>
274 </varlistentry>
275 <varlistentry>
276 <term>
277 <option>--cores</option>
278 </term>
279 <listitem>
280 <para>
281 Sets the value of the <envar>NIX_BUILD_CORES</envar> environment variable
282 in the invocation of builders. Builders can use this variable at their
283 discretion to control the maximum amount of parallelism. For instance, in
284 Nixpkgs, if the derivation attribute
285 <varname>enableParallelBuilding</varname> is set to
286 <literal>true</literal>, the builder passes the
287 <option>-j<replaceable>N</replaceable></option> flag to GNU Make. The
288 value <literal>0</literal> means that the builder should use all
289 available CPU cores in the system.
290 </para>
291 </listitem>
292 </varlistentry>
293 <varlistentry>
294 <term>
295 <option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable>
296 </term>
297 <listitem>
298 <para>
299 Set the Nix configuration option <replaceable>name</replaceable> to
300 <replaceable>value</replaceable>.
301 </para>
302 </listitem>
303 </varlistentry>
304 <varlistentry>
305 <term>
306 <option>--show-trace</option>
307 </term>
308 <listitem>
309 <para>
310 Causes Nix to print out a stack trace in case of Nix expression
311 evaluation errors.
312 </para>
313 </listitem>
314 </varlistentry>
315 <varlistentry>
316 <term>
317 <option>--keep-going</option>
318 </term>
319 <listitem>
320 <para>
321 Causes Nix to continue building derivations as far as possible
322 in the face of failed builds.
323 </para>
324 </listitem>
325 </varlistentry>
326 <varlistentry>
327 <term>
328 <option>--help</option>
329 </term>
330 <listitem>
331 <para>
332 Synonym for <command>man nixos-install</command>.
333 </para>
334 </listitem>
335 </varlistentry>
336 </variablelist>
337 </refsection>
338 <refsection>
339 <title>Examples</title>
340 <para>
341 A typical NixOS installation is done by creating and mounting a file system
342 on <filename>/mnt</filename>, generating a NixOS configuration in
343 <filename>/mnt/etc/nixos/configuration.nix</filename>, and running
344 <command>nixos-install</command>. For instance, if we want to install NixOS
345 on an <literal>ext4</literal> file system created in
346 <filename>/dev/sda1</filename>:
347<screen>
348<prompt>$ </prompt>mkfs.ext4 /dev/sda1
349<prompt>$ </prompt>mount /dev/sda1 /mnt
350<prompt>$ </prompt>nixos-generate-config --root /mnt
351<prompt>$ </prompt># edit /mnt/etc/nixos/configuration.nix
352<prompt>$ </prompt>nixos-install
353<prompt>$ </prompt>reboot
354</screen>
355 </para>
356 </refsection>
357</refentry>