nixos/doc/manual/man-nixos-install.xml

   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 '&lt;nixpkgs/nixos&gt;' -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>