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