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>
12 </refname><refpurpose>install bootloader and NixOS</refpurpose>
13 </refnamediv>
14 <refsynopsisdiv>
15 <cmdsynopsis>
16 <command>nixos-install</command>
17 <arg>
18 <arg choice='plain'>
19 <option>-I</option>
20 </arg>
21 <replaceable>path</replaceable>
22 </arg>
23
24 <arg>
25 <arg choice='plain'>
26 <option>--root</option>
27 </arg>
28 <replaceable>root</replaceable>
29 </arg>
30
31 <arg>
32 <arg choice='plain'>
33 <option>--system</option>
34 </arg>
35 <replaceable>path</replaceable>
36 </arg>
37
38 <arg>
39 <arg choice='plain'>
40 <option>--no-channel-copy</option>
41 </arg>
42 </arg>
43
44 <arg>
45 <arg choice='plain'>
46 <option>--no-root-passwd</option>
47 </arg>
48 </arg>
49
50 <arg>
51 <arg choice='plain'>
52 <option>--no-bootloader</option>
53 </arg>
54 </arg>
55
56 <arg>
57 <group choice='req'>
58 <arg choice='plain'>
59 <option>--max-jobs</option>
60 </arg>
61
62 <arg choice='plain'>
63 <option>-j</option>
64 </arg>
65 </group> <replaceable>number</replaceable>
66 </arg>
67
68 <arg>
69 <option>--cores</option> <replaceable>number</replaceable>
70 </arg>
71
72 <arg>
73 <option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable>
74 </arg>
75
76 <arg>
77 <arg choice='plain'>
78 <option>--show-trace</option>
79 </arg>
80 </arg>
81
82 <arg>
83 <arg choice='plain'>
84 <option>--help</option>
85 </arg>
86 </arg>
87 </cmdsynopsis>
88 </refsynopsisdiv>
89 <refsection>
90 <title>Description</title>
91 <para>
92 This command installs NixOS in the file system mounted on
93 <filename>/mnt</filename>, based on the NixOS configuration specified in
94 <filename>/mnt/etc/nixos/configuration.nix</filename>. It performs the
95 following steps:
96 <itemizedlist>
97 <listitem>
98 <para>
99 It copies Nix and its dependencies to
100 <filename>/mnt/nix/store</filename>.
101 </para>
102 </listitem>
103 <listitem>
104 <para>
105 It runs Nix in <filename>/mnt</filename> to build the NixOS configuration
106 specified in <filename>/mnt/etc/nixos/configuration.nix</filename>.
107 </para>
108 </listitem>
109 <listitem>
110 <para>
111 It installs the GRUB boot loader on the device specified in the option
112 <option>boot.loader.grub.device</option> (unless
113 <option>--no-bootloader</option> is specified), and generates a GRUB
114 configuration file that boots into the NixOS configuration just
115 installed.
116 </para>
117 </listitem>
118 <listitem>
119 <para>
120 It prompts you for a password for the root account (unless
121 <option>--no-root-passwd</option> is specified).
122 </para>
123 </listitem>
124 </itemizedlist>
125 </para>
126 <para>
127 This command is idempotent: if it is interrupted or fails due to a temporary
128 problem (e.g. a network issue), you can safely re-run it.
129 </para>
130 </refsection>
131 <refsection>
132 <title>Options</title>
133 <para>
134 This command accepts the following options:
135 </para>
136 <variablelist>
137 <varlistentry>
138 <term>
139 <option>--root</option>
140 </term>
141 <listitem>
142 <para>
143 Defaults to <filename>/mnt</filename>. If this option is given, treat the
144 directory <replaceable>root</replaceable> as the root of the NixOS
145 installation.
146 </para>
147 </listitem>
148 </varlistentry>
149 <varlistentry>
150 <term>
151 <option>--system</option>
152 </term>
153 <listitem>
154 <para>
155 If this option is provided, <command>nixos-install</command> will install
156 the specified closure rather than attempt to build one from
157 <filename>/mnt/etc/nixos/configuration.nix</filename>.
158 </para>
159 <para>
160 The closure must be an appropriately configured NixOS system, with boot
161 loader and partition configuration that fits the target host. Such a
162 closure is typically obtained with a command such as <command>nix-build
163 -I nixos-config=./configuration.nix '<nixos>' -A system
164 --no-out-link</command>
165 </para>
166 </listitem>
167 </varlistentry>
168 <varlistentry>
169 <term>
170 <option>-I</option>
171 </term>
172 <listitem>
173 <para>
174 Add a path to the Nix expression search path. This option may be given
175 multiple times. See the NIX_PATH environment variable for information on
176 the semantics of the Nix search path. Paths added through
177 <replaceable>-I</replaceable> take precedence over NIX_PATH.
178 </para>
179 </listitem>
180 </varlistentry>
181 <varlistentry>
182 <term>
183 <option>--max-jobs</option>
184 </term>
185 <term>
186 <option>-j</option>
187 </term>
188 <listitem>
189 <para>
190 Sets the maximum number of build jobs that Nix will perform in parallel
191 to the specified number. The default is <literal>1</literal>. A higher
192 value is useful on SMP systems or to exploit I/O latency.
193 </para>
194 </listitem>
195 </varlistentry>
196 <varlistentry>
197 <term>
198 <option>--cores</option>
199 </term>
200 <listitem>
201 <para>
202 Sets the value of the <envar>NIX_BUILD_CORES</envar> environment variable
203 in the invocation of builders. Builders can use this variable at their
204 discretion to control the maximum amount of parallelism. For instance, in
205 Nixpkgs, if the derivation attribute
206 <varname>enableParallelBuilding</varname> is set to
207 <literal>true</literal>, the builder passes the
208 <option>-j<replaceable>N</replaceable></option> flag to GNU Make. The
209 value <literal>0</literal> means that the builder should use all
210 available CPU cores in the system.
211 </para>
212 </listitem>
213 </varlistentry>
214 <varlistentry>
215 <term>
216 <option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable>
217 </term>
218 <listitem>
219 <para>
220 Set the Nix configuration option <replaceable>name</replaceable> to
221 <replaceable>value</replaceable>.
222 </para>
223 </listitem>
224 </varlistentry>
225 <varlistentry>
226 <term>
227 <option>--show-trace</option>
228 </term>
229 <listitem>
230 <para>
231 Causes Nix to print out a stack trace in case of Nix expression
232 evaluation errors.
233 </para>
234 </listitem>
235 </varlistentry>
236 <varlistentry>
237 <term>
238 <option>--help</option>
239 </term>
240 <listitem>
241 <para>
242 Synonym for <command>man nixos-install</command>.
243 </para>
244 </listitem>
245 </varlistentry>
246 </variablelist>
247 </refsection>
248 <refsection>
249 <title>Examples</title>
250 <para>
251 A typical NixOS installation is done by creating and mounting a file system
252 on <filename>/mnt</filename>, generating a NixOS configuration in
253 <filename>/mnt/etc/nixos/configuration.nix</filename>, and running
254 <command>nixos-install</command>. For instance, if we want to install NixOS
255 on an <literal>ext4</literal> file system created in
256 <filename>/dev/sda1</filename>:
257<screen>
258$ mkfs.ext4 /dev/sda1
259$ mount /dev/sda1 /mnt
260$ nixos-generate-config --root /mnt
261$ # edit /mnt/etc/nixos/configuration.nix
262$ nixos-install
263$ reboot
264</screen>
265 </para>
266 </refsection>
267</refentry>