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