NixOS Installation Guide
This guide serves as a companion guide for the official manual. It describes installation of NixOS as a complete operating system. For instructions on installing Nix within an existing operating system, refer to the Nix Installation Guide.
In addition to covering the steps from the official manual, it provides known good instructions for common use cases. When there is a discrepancy between the manual and this guide, the supported case is the one described in the manual.
Installation target
NixOS can be installed on an increasing variety of hardware:
- regular (Intel or AMD) desktop computers, laptops or physically accessible servers, covered on this page
- SBCs (like the Raspberry Pis) and other ARM boards, see NixOS on ARM
- cloud and remote servers, see NixOS friendly hosters
Installation method
NixOS, as with most Linux-based operating systems, can be installed in different ways.
- The classic way, booting from the installation media. (Described below.)
- Booting the media from an existing Linux installation
Making the installation media
Since NixOS 14.11 the installer ISO is hybrid. This means it is bootable on both CD and USB drives. It also boots on EFI systems, like most modern motherboards and apple systems. The following instructions will assume the standard way of copying the image to a USB drive. When using a CD or DVD, the usual methods to burn to disk should work with the iso.
"Burning" to USB drive
First, download a NixOS ISO image or create a custom ISO. Then plug in a USB stick large enough to accommodate the image. Then follow the platform instructions:
From Linux
- Find the right device with
lsblk
orfdisk -l
. Replace/dev/sdX
with the proper device in the following steps. - Copy to device:
cp nixos-xxx.iso /dev/sdX
Writing the disk image with dd if=nixos.iso of=/dev/sdX bs=4M status=progress conv=fdatasync
also works.
From macOS
- Find the right device with
diskutil list
, let's saydiskX
. - Unmount with
diskutil unmountDisk diskX
. - Burn with:
sudo dd if=path_to_nixos.iso of=/dev/diskX
rdiskX
instead of diskX
can makes a large speed difference. You can check the write speed with iostat 2
in another terminal.
From Windows
- Download USBwriter.
- Start USBwriter.
- Choose the downloaded ISO as 'Source'
- Choose the USB drive as 'Target'
- Click 'Write'
- When USBwriter has finished writing, safely unplug the USB drive.
Alternative installation media instructions
The previous methods are the supported methods of making the USB installation media.
Those methods are also documented, they can allow using the USB drive to boot multiple distributions. This is not supported, your mileage may vary.
Booting the installation media
The installation media is hybrid and is capable of booting in both legacy BIOS mode and UEFI mode.
Whatever mode is used to boot the installation media, your motherboard or computer's configuration may need to be changed to allow booting from a Optical Disk Drive (for CD/DVD) or an external USB drive.
Legacy bios boot
This is the only boot possible on machines lacking EFI/UEFI.
UEFI boot
The EFI bootloader of the installation media is not signed and is not using a signed shim to boot. This means that Secure Boot will need to be disabled to boot.
Connecting to the internet
The installation will definitely need a working internet connection. It is possible to install without one, but the available set of packages is limited.
Wired
For network interfaces supported by the kernel, DHCP resolution should already have happened once the shell is available.
Tethered (Internet Sharing)
If you can not connect to the internet via cable or wifi, you may use smartphone's tethering capability to share internet. Depending on your smartphones capabilities, only stock kernel drivers may be required which can help providing a working network connection.
Wireless
NetworkManager is installed on the graphical ISO, meaning that it is possible to use nmtui
on the command line to connect to a network.
Using the "Applications" tab at top
left or the launcher bar at bottom, choose a terminal application and from there launch nmtui
. This will allow you to 'activate' a (wireless) connection - your local SSIDs should be visible in the list, else you can add a new connection. When the wireless connection is active and you have tested it, it is likely the install app which launched on startup has not detected the new connection. Close down the install app, and reopen it from the launcher bar at the bottom of the screen. This should then find the new connection and proceed.
On the minimal ISO, or if you are more familiar with wpa_supplicant then you can also run wpa_passphrase ESSID | sudo tee /etc/wpa_supplicant.conf
, then enter your password and systemctl restart wpa_supplicant
.
Partitioning
To partition the persistent storage run sudo fdisk /dev/diskX
and follow instructions for MBR or (U)EFI. To determine which mode you are booted into, run:
$ [ -d /sys/firmware/efi/efivars ] && echo "UEFI" || echo "Legacy"
A very simple example setup is given here.
Legacy Boot (MBR)
- o (dos disk label)
- n new
- p primary (4 primary in total)
- 1 (partition number [1/4])
- 2048 first sector (alignment for performance)
- +500M last sector (boot sector size)
- rm signature (Y), if ex. => warning of overwriting existing system, could use wipefs
- n
- p
- 2
- default (fill up partition)
- default (fill up partition)
- w (write)
UEFI
- g (gpt disk label)
- n
- 1 (partition number [1/128])
- 2048 first sector
- +500M last sector (boot sector size)
- t
- 1 (EFI System)
- n
- 2
- default (fill up partition)
- default (fill up partition)
- w (write)
Format partitions
The example below uses the ext4 filesystem format. If you wish to use other filesystem formats such as Btrfs or ZFS:
- Bcachefs#NixOS installation on bcachefs
- Btrfs#Installation of NixOS on btrfs
- LVM#Basic Setup
- ZFS#Simple NixOS ZFS on root installation
This is useful for having multiple setups and makes partitions easier to handle
$ lsblk # lists current system block devices
# mkfs.fat -F 32 -n boot /dev/sdX1
# mkfs.ext4 /dev/sdX2 -L nixos
# mount /dev/disk/by-label/boot /mnt
# mkdir -p /mnt/boot
# mount /dev/disk/by-label/boot /mnt/boot
NixOS configuration
NixOS is configured through a declarative configuration file. To generate a default config file, run nixos-generate-config:
# nixos-generate-config --root /mnt
# nano /mnt/etc/nixos/configuration.nix
Most essential changes:
- keyboard layout, ie
services.xserver.xkb.layout
- networking (wifi), see below for fix if it breaks
- install editor to edit the configuration
The self-documenting NixOS options can be searched with NixOS options search.
Swap file
For additional methods of configuring swap, see Swap. The following example demonstrates how to create and enable a swap file:
swapDevices = [{
device = "/var/lib/swapfile";
size = 16*1024; # 16 GB
}];
Bootloader
NixOS supports multiple bootloaders such as GNU GRUB and Systemd/boot.
Sysyemd-boot is the recommended bootloader. The following example demonstrates how to enable systemd-boot in your configuration:
boot.loader.systemd-boot.enable = true;
You may also wish to configure Secure Boot.
Users
For information on creating and managing users, see User management and the NixOS Manual: Chapter - Package Management. See an example below:
users.users.alice = {
isNormalUser = true;
initialPassword = "pw123";
};
NixOS installation
# cd /mnt
# nixos-install
after installation: Run passwd
to change user password.
if internet broke/breaks, try one of the following:
# nixos-rebuild switch --option substitute false # no downloads
# nixos-rebuild switch --option binary-caches "" # no downloads
- wpa_supplicant flags to connect to wifi
Additional notes for specific hardware
These are collected notes or links for specific hardware issues.
- Blog post how to install NixOS on a Dell 9560
- Brand servers may require extra kernel modules be included into initrd (
boot.initrd.extraKernelModules
in configuration.nix) For example HP Proliant needs "hpsa" module to see the disk drive.