path: root/nixos/doc/manual/man-nixos-install.xml

<refentry xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:xi="http://www.w3.org/2001/XInclude">
 <refmeta>
  <refentrytitle><command>nixos-install</command>
  </refentrytitle><manvolnum>8</manvolnum>
  <refmiscinfo class="source">NixOS</refmiscinfo>
<!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->
 </refmeta>
 <refnamediv>
  <refname><command>nixos-install</command></refname>
  <refpurpose>install bootloader and NixOS</refpurpose>
 </refnamediv>
 <refsynopsisdiv>
  <cmdsynopsis>
   <command>nixos-install</command>
   <arg>
    <group choice='req'>
     <arg choice='plain'>
      <option>--verbose</option>
     </arg>
     <arg choice='plain'>
      <option>-v</option>
     </arg>
    </group>
   </arg>
   <arg>
    <arg choice='plain'>
     <option>-I</option>
    </arg>
     <replaceable>path</replaceable>
   </arg>

   <arg>
    <arg choice='plain'>
     <option>--root</option>
    </arg>
     <replaceable>root</replaceable>
   </arg>

   <arg>
    <arg choice='plain'>
     <option>--system</option>
    </arg>
     <replaceable>path</replaceable>
   </arg>

   <arg>
    <option>--flake</option> <replaceable>flake-uri</replaceable>
   </arg>

   <arg>
    <group choice='req'>
     <arg choice='plain'><option>--impure</option></arg>
    </group>
   </arg>

   <arg>
     <arg choice='plain'>
       <option>--channel</option>
     </arg>
     <replaceable>channel</replaceable>
   </arg>

   <arg>
    <arg choice='plain'>
     <option>--no-channel-copy</option>
    </arg>
   </arg>

   <arg>
    <group choice='req'>
     <arg choice='plain'>
      <option>--no-root-password</option>
     </arg>
     <arg choice='plain'>
      <option>--no-root-passwd</option>
     </arg>
    </group>
   </arg>

   <arg>
    <arg choice='plain'>
     <option>--no-bootloader</option>
    </arg>
   </arg>

   <arg>
    <group choice='req'>
    <arg choice='plain'>
     <option>--max-jobs</option>
    </arg>

    <arg choice='plain'>
     <option>-j</option>
    </arg>
     </group> <replaceable>number</replaceable>
   </arg>

   <arg>
    <option>--cores</option> <replaceable>number</replaceable>
   </arg>

   <arg>
    <option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable>
   </arg>

   <arg>
    <arg choice='plain'>
     <option>--show-trace</option>
    </arg>
   </arg>

   <arg>
    <arg choice='plain'>
     <option>--keep-going</option>
    </arg>
   </arg>

   <arg>
    <arg choice='plain'>
     <option>--help</option>
    </arg>
   </arg>
  </cmdsynopsis>
 </refsynopsisdiv>
 <refsection>
  <title>Description</title>
  <para>
   This command installs NixOS in the file system mounted on
   <filename>/mnt</filename>, based on the NixOS configuration specified in
   <filename>/mnt/etc/nixos/configuration.nix</filename>. It performs the
   following steps:
   <itemizedlist>
    <listitem>
     <para>
      It copies Nix and its dependencies to
      <filename>/mnt/nix/store</filename>.
     </para>
    </listitem>
    <listitem>
     <para>
      It runs Nix in <filename>/mnt</filename> to build the NixOS configuration
      specified in <filename>/mnt/etc/nixos/configuration.nix</filename>.
     </para>
    </listitem>
    <listitem>
      <para>
        It installs the current channel <quote>nixos</quote> in the target channel
        profile (unless <option>--no-channel-copy</option> is specified).
      </para>
    </listitem>
    <listitem>
     <para>
      It installs the GRUB boot loader on the device specified in the option
      <option>boot.loader.grub.device</option> (unless
      <option>--no-bootloader</option> is specified), and generates a GRUB
      configuration file that boots into the NixOS configuration just
      installed.
     </para>
    </listitem>
    <listitem>
     <para>
      It prompts you for a password for the root account (unless
      <option>--no-root-password</option> is specified).
     </para>
    </listitem>
   </itemizedlist>
  </para>
  <para>
   This command is idempotent: if it is interrupted or fails due to a temporary
   problem (e.g. a network issue), you can safely re-run it.
  </para>
 </refsection>
 <refsection>
  <title>Options</title>
  <para>
   This command accepts the following options:
  </para>
  <variablelist>
   <varlistentry>
    <term><option>--verbose</option> / <option>-v</option></term>
    <listitem>
     <para>Increases the level of verbosity of diagnostic messages
     printed on standard error.  For each Nix operation, the information
     printed on standard output is well-defined; any diagnostic
     information is printed on standard error, never on standard
     output.</para>
     <para>Please note that this option may be specified repeatedly.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--root</option>
    </term>
    <listitem>
     <para>
      Defaults to <filename>/mnt</filename>. If this option is given, treat the
      directory <replaceable>root</replaceable> as the root of the NixOS
      installation.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--system</option>
    </term>
    <listitem>
     <para>
      If this option is provided, <command>nixos-install</command> will install
      the specified closure rather than attempt to build one from
      <filename>/mnt/etc/nixos/configuration.nix</filename>.
     </para>
     <para>
      The closure must be an appropriately configured NixOS system, with boot
      loader and partition configuration that fits the target host. Such a
      closure is typically obtained with a command such as <command>nix-build
      -I nixos-config=./configuration.nix '&lt;nixpkgs/nixos&gt;' -A system
      --no-out-link</command>
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--flake</option> <replaceable>flake-uri</replaceable>#<replaceable>name</replaceable>
    </term>
    <listitem>
     <para>
      Build the NixOS system from the specified flake.
      The flake must contain an output named
      <literal>nixosConfigurations.<replaceable>name</replaceable></literal>.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
     <term>
       <option>--channel</option>
     </term>
     <listitem>
       <para>
         If this option is provided, do not copy the current
         <quote>nixos</quote> channel to the target host. Instead, use the
         specified derivation.
       </para>
     </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>-I</option>
    </term>
    <listitem>
     <para>
      Add a path to the Nix expression search path. This option may be given
      multiple times. See the NIX_PATH environment variable for information on
      the semantics of the Nix search path. Paths added through
      <replaceable>-I</replaceable> take precedence over NIX_PATH.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--max-jobs</option>
    </term>
    <term>
     <option>-j</option>
    </term>
    <listitem>
     <para>
      Sets the maximum number of build jobs that Nix will perform in parallel
      to the specified number. The default is <literal>1</literal>. A higher
      value is useful on SMP systems or to exploit I/O latency.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--cores</option>
    </term>
    <listitem>
     <para>
      Sets the value of the <envar>NIX_BUILD_CORES</envar> environment variable
      in the invocation of builders. Builders can use this variable at their
      discretion to control the maximum amount of parallelism. For instance, in
      Nixpkgs, if the derivation attribute
      <varname>enableParallelBuilding</varname> is set to
      <literal>true</literal>, the builder passes the
      <option>-j<replaceable>N</replaceable></option> flag to GNU Make. The
      value <literal>0</literal> means that the builder should use all
      available CPU cores in the system.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable>
    </term>
    <listitem>
     <para>
      Set the Nix configuration option <replaceable>name</replaceable> to
      <replaceable>value</replaceable>.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--show-trace</option>
    </term>
    <listitem>
     <para>
      Causes Nix to print out a stack trace in case of Nix expression
      evaluation errors.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--keep-going</option>
    </term>
    <listitem>
     <para>
      Causes Nix to continue building derivations as far as possible
      in the face of failed builds.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <option>--help</option>
    </term>
    <listitem>
     <para>
      Synonym for <command>man nixos-install</command>.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsection>
 <refsection>
  <title>Examples</title>
  <para>
   A typical NixOS installation is done by creating and mounting a file system
   on <filename>/mnt</filename>, generating a NixOS configuration in
   <filename>/mnt/etc/nixos/configuration.nix</filename>, and running
   <command>nixos-install</command>. For instance, if we want to install NixOS
   on an <literal>ext4</literal> file system created in
   <filename>/dev/sda1</filename>:
<screen>
<prompt>$ </prompt>mkfs.ext4 /dev/sda1
<prompt>$ </prompt>mount /dev/sda1 /mnt
<prompt>$ </prompt>nixos-generate-config --root /mnt
<prompt>$ </prompt># edit /mnt/etc/nixos/configuration.nix
<prompt>$ </prompt>nixos-install
<prompt>$ </prompt>reboot
</screen>
  </para>
 </refsection>
</refentry>