path: root/nixos/doc/manual/man-nixos-rebuild.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-rebuild</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-rebuild</command></refname>
  <refpurpose>reconfigure a NixOS machine</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <cmdsynopsis>
   <command>nixos-rebuild</command><group choice='req'>
   <arg choice='plain'>
    <option>switch</option>
   </arg>

   <arg choice='plain'>
    <option>boot</option>
   </arg>

   <arg choice='plain'>
    <option>test</option>
   </arg>

   <arg choice='plain'>
    <option>build</option>
   </arg>

   <arg choice='plain'>
    <option>dry-build</option>
   </arg>

   <arg choice='plain'>
    <option>dry-activate</option>
   </arg>

   <arg choice='plain'>
    <option>edit</option>
   </arg>

   <arg choice='plain'>
    <option>build-vm</option>
   </arg>

   <arg choice='plain'>
    <option>build-vm-with-bootloader</option>
   </arg>
    </group>
    <sbr />

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

   <arg>
    <option>--install-bootloader</option>
   </arg>

   <arg>
    <option>--no-build-nix</option>
   </arg>

   <arg>
    <option>--fast</option>
   </arg>

   <arg>
    <option>--rollback</option>
   </arg>

   <arg>
    <option>--builders</option> <replaceable>builder-spec</replaceable>
   </arg>

   <sbr/>

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

   <sbr />

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

    <arg choice='plain'>
     <option>-p</option>
    </arg>
     </group> <replaceable>name</replaceable>
   </arg>
   <sbr />
   <arg>
    <option>--show-trace</option>
   </arg>
   <arg>
    <option>-I</option>
    <replaceable>path</replaceable>
   </arg>
   <arg>
    <option>-L</option>
   </arg>
   <arg>
    <option>--refresh</option>
   </arg>
   <arg>
    <option>--no-net</option>
   </arg>
   <arg>
    <option>--impure</option>
   </arg>
   <arg>
    <group choice='req'>
     <arg choice='plain'><option>--verbose</option></arg>
     <arg choice='plain'><option>-v</option></arg>
    </group>
   </arg>
   <arg>
    <group choice='req'>
     <arg choice='plain'><option>--impure</option></arg>
    </group>
   </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>--fallback</option>
   </arg>
   <arg>
    <option>--repair</option>
   </arg>
   <arg>
    <group choice='req'>
     <arg choice='plain'><option>--no-build-output</option></arg>
     <arg choice='plain'><option>-Q</option></arg>
    </group>
   </arg>
   <arg>
    <group choice='req'>
     <arg choice='plain'><option>--keep-failed</option></arg>
     <arg choice='plain'><option>-K</option></arg>
    </group>
   </arg>
   <arg>
    <group choice='req'>
     <arg choice='plain'><option>--keep-going</option></arg>
     <arg choice='plain'><option>-k</option></arg>
    </group>
   </arg>
  </cmdsynopsis>
 </refsynopsisdiv>

 <refsection>
  <title>Description</title>

  <para>
   This command updates the system so that it corresponds to the
   configuration specified in
   <filename>/etc/nixos/configuration.nix</filename> or
   <filename>/etc/nixos/flake.nix</filename>. Thus, every time you
   modify the configuration or any other NixOS module, you must run
   <command>nixos-rebuild</command> to make the changes take
   effect. It builds the new system in
   <filename>/nix/store</filename>, runs its activation script, and
   stop and (re)starts any system services if needed. Please note that
   user services need to be started manually as they aren't detected
   by the activation script at the moment.
  </para>

  <para>
   This command has one required argument, which specifies the desired
   operation. It must be one of the following:

   <variablelist>
    <varlistentry>
     <term>
      <option>switch</option>
     </term>
     <listitem>
      <para>
       Build and activate the new configuration, and make it the boot default.
       That is, the configuration is added to the GRUB boot menu as the default
       menu entry, so that subsequent reboots will boot the system into the new
       configuration. Previous configurations activated with
       <command>nixos-rebuild switch</command> or <command>nixos-rebuild
       boot</command> remain available in the GRUB menu.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>
      <option>boot</option>
     </term>
     <listitem>
      <para>
       Build the new configuration and make it the boot default (as with
       <command>nixos-rebuild switch</command>), but do not activate it. That
       is, the system continues to run the previous configuration until the
       next reboot.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>
      <option>test</option>
     </term>
     <listitem>
      <para>
       Build and activate the new configuration, but do not add it to the GRUB
       boot menu. Thus, if you reboot the system (or if it crashes), you will
       automatically revert to the default configuration (i.e. the
       configuration resulting from the last call to <command>nixos-rebuild
       switch</command> or <command>nixos-rebuild boot</command>).
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>
      <option>build</option>
     </term>
     <listitem>
      <para>
       Build the new configuration, but neither activate it nor add it to the
       GRUB boot menu. It leaves a symlink named <filename>result</filename> in
       the current directory, which points to the output of the top-level
       “system” derivation. This is essentially the same as doing
<screen>
<prompt>$ </prompt>nix-build /path/to/nixpkgs/nixos -A system
</screen>
       Note that you do not need to be <literal>root</literal> to run
       <command>nixos-rebuild build</command>.
      </para>
     </listitem>
    </varliste