···
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="sec-installation">
<title>Installing NixOS</title>
<section xml:id="sec-installation-booting">
+
<title>Booting from the install medium</title>
+
To begin the installation, you have to boot your computer from the
+
<orderedlist numeration="arabic">
+
Plug in the install drive. Then turn on or restart your
+
Open the boot menu by pressing the appropriate key, which is
+
usually shown on the display on early boot. Select the USB
+
flash drive (the option usually contains the word
+
<quote>USB</quote>). If you choose the incorrect drive, your
+
computer will likely continue to boot as normal. In that case
+
restart your computer and pick a different drive.
+
The key to open the boot menu is different across computer
+
brands and even models. It can be <keycap>F12</keycap>, but
+
also <keycap>F1</keycap>, <keycap>F9</keycap>,
+
<keycap>F10</keycap>, <keycap>Enter</keycap>,
+
<keycap>Del</keycap>, <keycap>Esc</keycap> or another
+
function key. If you are unsure and don’t see it on the
+
early boot screen, you can search online for your computers
+
brand, model followed by <quote>boot from usb</quote>. The
+
computer might not even have that feature, so you have to go
+
into the BIOS/UEFI settings to change the boot order. Again,
+
search online for details about your specific computer
+
For Apple computers with Intel processors press and hold the
+
<keycap>⌥</keycap> (Option or Alt) key until you see the
+
boot menu. On Apple silicon press and hold the power button.
+
If your computer supports both BIOS and UEFI boot, choose
+
If you use a CD for the installation, the computer will
+
probably boot from it automatically. If not, choose the
+
option containing the word <quote>CD</quote> from the boot
+
Shortly after selecting the appropriate boot drive, you should
+
be presented with a menu with different installer options.
+
Leave the default and wait (or press <keycap>Enter</keycap> to
+
The graphical images will start their corresponding desktop
+
environment and the graphical installer, which can take some
+
time. The minimal images will boot to a command line. You have
+
to follow the instructions in
+
<xref linkend="sec-installation-manual" /> there.
+
<section xml:id="sec-installation-graphical">
+
<title>Graphical Installation</title>
+
The graphical installer is recommended for desktop users and will
+
guide you through the installation.
+
<orderedlist numeration="arabic">
+
In the <quote>Welcome</quote> screen, you can select the
+
language of the Installer and the installed system.
+
Leaving the language as <quote>American English</quote> will
+
make it easier to search for error messages in a search
+
engine or to report an issue.
+
Next you should choose your location to have the timezone set
+
correctly. You can actually click on the map!
+
The installer will use an online service to guess your
+
location based on your public IP address.
+
Then you can select the keyboard layout. The default keyboard
+
model should work well with most desktop keyboards. If you
+
have a special keyboard or notebook, your model might be in
+
the list. Select the language you are most comfortable typing
+
On the <quote>Users</quote> screen, you have to type in your
+
display name, login name and password. You can also enable an
+
option to automatically login to the desktop.
+
Then you have the option to choose a desktop environment. If
+
you want to create a custom setup with a window manager, you
+
can select <quote>No desktop</quote>.
+
If you don’t have a favorite desktop and don’t know which
+
one to choose, you can stick to either GNOME or Plasma. They
+
have a quite different design, so you should choose
+
whichever you like better. They are both popular choices and
+
You have the option to allow unfree software in the next
+
The easiest option in the <quote>Partitioning</quote> screen
+
is <quote>Erase disk</quote>, which will delete all data from
+
the selected disk and install the system on it. Also select
+
<quote>Swap (with Hibernation)</quote> in the dropdown below
+
it. You have the option to encrypt the whole disk with LUKS.
+
At the top left you see if the Installer was booted with
+
BIOS or UEFI. If you know your system supports UEFI and it
+
shows <quote>BIOS</quote>, reboot with the correct option.
+
Make sure you have selected the correct disk at the top and
+
that no valuable data is still on the disk! It will be
+
deleted when formatting the disk.
+
Check the choices you made in the <quote>Summary</quote> and
+
click <quote>Install</quote>.
+
The installation takes about 15 minutes. The time varies
+
based on the selected desktop environment, internet
+
connection speed and disk write speed.
+
When the install is complete, remove the USB flash drive and
+
reboot into your new system!
+
<section xml:id="sec-installation-manual">
+
<title>Manual Installation</title>
+
NixOS can be installed on BIOS or UEFI systems. The procedure for
+
a UEFI installation is broadly the same as for a BIOS
+
installation. The differences are mentioned in the following
The NixOS manual is available by running
+
<literal>nixos-help</literal> in the command line or from the
+
application menu in the desktop environment.
+
To have access to the command line on the graphical images, open
+
Terminal (GNOME) or Konsole (Plasma) from the application menu.
You are logged-in automatically as <literal>nixos</literal>. The
···
+
You can use <literal>loadkeys</literal> to switch to your
+
preferred keyboard layout. (We even provide neo2 via
<literal>loadkeys de neo</literal>!)
···
bootloader lists boot entries, select the serial console boot
+
<section xml:id="sec-installation-manual-networking">
<title>Networking in the installer</title>
+
<anchor xml:id="sec-installation-booting-networking" />
The boot process should have brought up networking (check
<literal>ip a</literal>). Networking is necessary for the
···
+
<section xml:id="sec-installation-manual-partitioning">
+
<title>Partitioning and formatting</title>
+
<anchor xml:id="sec-installation-partitioning" />
+
The NixOS installer doesn’t do any partitioning or formatting,
+
so you need to do that yourself.
+
The NixOS installer ships with multiple partitioning tools. The
+
examples below use <literal>parted</literal>, but also provides
+
<literal>fdisk</literal>, <literal>gdisk</literal>,
+
<literal>cfdisk</literal>, and <literal>cgdisk</literal>.
+
The recommended partition scheme differs depending if the
+
computer uses <emphasis>Legacy Boot</emphasis> or
+
<emphasis>UEFI</emphasis>.
+
<section xml:id="sec-installation-manual-partitioning-UEFI">
+
<title>UEFI (GPT)</title>
+
<anchor xml:id="sec-installation-partitioning-UEFI" />
+
Here's an example partition scheme for UEFI, using
+
<literal>/dev/sda</literal> as the device.
+
You can safely ignore <literal>parted</literal>'s
+
informational message about needing to update /etc/fstab.
+
<orderedlist numeration="arabic">
+
Create a <emphasis>GPT</emphasis> partition table.
# parted /dev/sda -- mklabel gpt
+
Add the <emphasis>root</emphasis> partition. This will
+
fill the disk except for the end part, where the swap will
+
live, and the space left in front (512MiB) which will be
+
used by the boot partition.
# parted /dev/sda -- mkpart primary 512MB -8GB
+
Next, add a <emphasis>swap</emphasis> partition. The size
+
required will vary according to needs, here a 8GB one is
# parted /dev/sda -- mkpart primary linux-swap -8GB 100%
+
The swap partition size rules are no different than for
+
other Linux distributions.
+
Finally, the <emphasis>boot</emphasis> partition. NixOS by
+
default uses the ESP (EFI system partition) as its
+
<emphasis>/boot</emphasis> partition. It uses the
+
initially reserved 512MiB at the start of the disk.
# parted /dev/sda -- mkpart ESP fat32 1MB 512MB
# parted /dev/sda -- set 3 esp on
+
Once complete, you can follow with
+
<xref linkend="sec-installation-manual-partitioning-formatting" />.
+
<section xml:id="sec-installation-manual-partitioning-MBR">
+
<title>Legacy Boot (MBR)</title>
+
<anchor xml:id="sec-installation-partitioning-MBR" />
+
Here's an example partition scheme for Legacy Boot, using
+
<literal>/dev/sda</literal> as the device.
+
You can safely ignore <literal>parted</literal>'s
+
informational message about needing to update /etc/fstab.
+
<orderedlist numeration="arabic">
+
Create a <emphasis>MBR</emphasis> partition table.
# parted /dev/sda -- mklabel msdos
+
Add the <emphasis>root</emphasis> partition. This will
+
fill the the disk except for the end part, where the swap
# parted /dev/sda -- mkpart primary 1MB -8GB
+
Set the root partition’s boot flag to on. This allows the
+
disk to be booted from.
# parted /dev/sda -- set 1 boot on
+
Finally, add a <emphasis>swap</emphasis> partition. The
+
size required will vary according to needs, here a 8GiB
# parted /dev/sda -- mkpart primary linux-swap -8GB 100%
+
The swap partition size rules are no different than for
+
other Linux distributions.
+
Once complete, you can follow with
+
<xref linkend="sec-installation-manual-partitioning-formatting" />.
+
<section xml:id="sec-installation-manual-partitioning-formatting">
+
<title>Formatting</title>
+
<anchor xml:id="sec-installation-partitioning-formatting" />
+
Use the following commands:
+
For initialising Ext4 partitions:
+
<literal>mkfs.ext4</literal>. It is recommended that you
+
assign a unique symbolic label to the file system using
+
the option <literal>-L label</literal>, since this makes
+
the file system configuration independent from device
+
# mkfs.ext4 -L nixos /dev/sda1
+
For creating swap partitions: <literal>mkswap</literal>.
+
Again it’s recommended to assign a label to the swap
+
partition: <literal>-L label</literal>. For example:
+
# mkswap -L swap /dev/sda2
+
<emphasis role="strong">UEFI systems</emphasis>
+
For creating boot partitions: <literal>mkfs.fat</literal>.
+
Again it’s recommended to assign a label to the boot
+
partition: <literal>-n label</literal>. For example:
+
# mkfs.fat -F 32 -n boot /dev/sda3
+
For creating LVM volumes, the LVM commands, e.g.,
+
<literal>pvcreate</literal>, <literal>vgcreate</literal>,
+
and <literal>lvcreate</literal>.
+
For creating software RAID devices, use
+
<literal>mdadm</literal>.
+
<section xml:id="sec-installation-manual-installing">
+
<title>Installing</title>
+
<anchor xml:id="sec-installation-installing" />
+
<orderedlist numeration="arabic">
+
Mount the target file system on which NixOS should be
+
installed on <literal>/mnt</literal>, e.g.
+
# mount /dev/disk/by-label/nixos /mnt
+
<emphasis role="strong">UEFI systems</emphasis>
+
Mount the boot file system on <literal>/mnt/boot</literal>,
+
# mount /dev/disk/by-label/boot /mnt/boot
+
If your machine has a limited amount of memory, you may want
+
to activate swap devices now
+
(<literal>swapon device</literal>). The installer (or
+
rather, the build actions that it may spawn) may need quite
+
a bit of RAM, depending on your configuration.
+
You now need to create a file
+
<literal>/mnt/etc/nixos/configuration.nix</literal> that
+
specifies the intended configuration of the system. This is
+
because NixOS has a <emphasis>declarative</emphasis>
+
configuration model: you create or edit a description of the
+
desired configuration of your system, and then NixOS takes
+
care of making it happen. The syntax of the NixOS
+
configuration file is described in
+
<xref linkend="sec-configuration-syntax" />, while a list of
+
available configuration options appears in
+
<xref linkend="ch-options" />. A minimal example is shown in
+
<link linkend="ex-config">Example: NixOS
+
The command <literal>nixos-generate-config</literal> can
+
generate an initial configuration file for you:
# nixos-generate-config --root /mnt
+
<literal>/mnt/etc/nixos/configuration.nix</literal> to suit
# nano /mnt/etc/nixos/configuration.nix
+
If you’re using the graphical ISO image, other editors may
+
be available (such as <literal>vim</literal>). If you have
+
network access, you can also install other editors – for
+
instance, you can install Emacs by running
+
<literal>nix-env -f '<nixpkgs>' -iA emacs</literal>.
+
You <emphasis>must</emphasis> set the option
+
<xref linkend="opt-boot.loader.grub.device" /> to
+
specify on which disk the GRUB boot loader is to be
+
installed. Without it, NixOS cannot boot.
+
If there are other operating systems running on the
+
machine before installing NixOS, the
+
<xref linkend="opt-boot.loader.grub.useOSProber" />
+
option can be set to <literal>true</literal> to
+
automatically add them to the grub menu.
+
You must select a boot-loader, either system-boot or
+
GRUB. The recommended option is systemd-boot: set the
+
<xref linkend="opt-boot.loader.systemd-boot.enable" />
+
to <literal>true</literal>.
+
<literal>nixos-generate-config</literal> should do
+
this automatically for new configurations when booted
+
You may want to look at the options starting with
+
<link linkend="opt-boot.loader.efi.canTouchEfiVariables"><literal>boot.loader.efi</literal></link>
+
<link linkend="opt-boot.loader.systemd-boot.enable"><literal>boot.loader.systemd-boot</literal></link>
+
If you want to use GRUB, set
+
<xref linkend="opt-boot.loader.grub.device" /> to
+
<literal>nodev</literal> and
+
<xref linkend="opt-boot.loader.grub.efiSupport" /> to
+
<literal>true</literal>.
+
With system-boot, you should not need any special
+
configuration to detect other installed systems. With
+
<xref linkend="opt-boot.loader.grub.useOSProber" /> to
+
<literal>true</literal>, but this will only detect
+
windows partitions, not other linux distributions. If
+
you dual boot another linux distribution, use
+
If you need to configure networking for your machine the
+
configuration options are described in
+
<xref linkend="sec-networking" />. In particular, while wifi
+
is supported on the installation image, it is not enabled by
+
default in the configuration generated by
+
<literal>nixos-generate-config</literal>.
+
Another critical option is <literal>fileSystems</literal>,
+
specifying the file systems that need to be mounted by
+
NixOS. However, you typically don’t need to set it yourself,
+
because <literal>nixos-generate-config</literal> sets it
+
<literal>/mnt/etc/nixos/hardware-configuration.nix</literal>
+
from your currently mounted file systems. (The configuration
+
file <literal>hardware-configuration.nix</literal> is
+
included from <literal>configuration.nix</literal> and will
+
be overwritten by future invocations of
+
<literal>nixos-generate-config</literal>; thus, you
+
generally should not modify it.) Additionally, you may want
+
<link xlink:href="https://github.com/NixOS/nixos-hardware">Hardware
+
configuration for known-hardware</link> at this point or
+
Depending on your hardware configuration or type of file
+
system, you may need to set the option
+
<literal>boot.initrd.kernelModules</literal> to include
+
the kernel modules that are necessary for mounting the
+
root file system, otherwise the installed system will not
+
be able to boot. (If this happens, boot from the
+
installation media again, mount the target file system on
+
<literal>/mnt</literal>, fix
+
<literal>/mnt/etc/nixos/configuration.nix</literal> and
+
rerun <literal>nixos-install</literal>.) In most cases,
+
<literal>nixos-generate-config</literal> will figure out
+
This will install your system based on the configuration you
+
provided. If anything fails due to a configuration problem
+
or any other issue (such as a network outage while
+
downloading binaries from the NixOS binary cache), you can
+
re-run <literal>nixos-install</literal> after fixing your
+
<literal>configuration.nix</literal>.
+
As the last step, <literal>nixos-install</literal> will ask
+
you to set the password for the <literal>root</literal>
+
For unattended installations, it is possible to use
+
<literal>nixos-install --no-root-passwd</literal> in order
+
to disable the password prompt entirely.
+
If everything went well:
+
You should now be able to boot into the installed NixOS. The
+
GRUB boot menu shows a list of <emphasis>available
+
configurations</emphasis> (initially just one). Every time
+
you change the NixOS configuration (see
+
<link linkend="sec-changing-config">Changing
+
Configuration</link>), a new item is added to the menu. This
+
allows you to easily roll back to a previous configuration
+
if something goes wrong.
+
You should log in and change the <literal>root</literal>
+
password with <literal>passwd</literal>.
+
You’ll probably want to create some user accounts as well,
+
which can be done with <literal>useradd</literal>:
$ useradd -c 'Eelco Dolstra' -m eelco
+
You may also want to install some software. This will be
+
covered in <xref linkend="sec-package-management" />.
+
<section xml:id="sec-installation-manual-summary">
+
<title>Installation summary</title>
+
<anchor xml:id="sec-installation-summary" />
+
To summarise, <link linkend="ex-install-sequence">Example:
+
Commands for Installing NixOS on
+
<literal>/dev/sda</literal></link> shows a typical sequence of
+
commands for installing NixOS on an empty hard drive (here
+
<literal>/dev/sda</literal>). <link linkend="ex-config">Example:
+
NixOS Configuration</link> shows a corresponding configuration
+
<anchor xml:id="ex-partition-scheme-MBR" />
+
<emphasis role="strong">Example: Example partition schemes for
+
NixOS on <literal>/dev/sda</literal> (MBR)</emphasis>
# parted /dev/sda -- mklabel msdos
# parted /dev/sda -- mkpart primary 1MiB -8GiB
# parted /dev/sda -- mkpart primary linux-swap -8GiB 100%
+
<anchor xml:id="ex-partition-scheme-UEFI" />
+
<emphasis role="strong">Example: Example partition schemes for
+
NixOS on <literal>/dev/sda</literal> (UEFI)</emphasis>
# parted /dev/sda -- mklabel gpt
# parted /dev/sda -- mkpart primary 512MiB -8GiB
# parted /dev/sda -- mkpart primary linux-swap -8GiB 100%
# parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB
# parted /dev/sda -- set 3 esp on
+
<anchor xml:id="ex-install-sequence" />
+
<emphasis role="strong">Example: Commands for Installing NixOS
+
on <literal>/dev/sda</literal></emphasis>
+
With a partitioned disk.
# mkfs.ext4 -L nixos /dev/sda1
# mkswap -L swap /dev/sda2
···
+
<anchor xml:id="ex-config" />
+
<emphasis role="strong">Example: NixOS Configuration</emphasis>
# Include the results of the hardware scan.
···
services.sshd.enable = true;
<section xml:id="sec-installation-additional-notes">
<title>Additional installation notes</title>
pyrox.dev