NixOS – Installation Guide

About

• Purely functional Linux distribution.
• Uses Nix package manager.

Table of Contents

1. Obtaining NixOS

Get NixOS and verify the integrity of the ISO.

grep nixos-graphical-19.03.172138.5c52b25283a-x86_64-linux.iso nixos-graphical-19.03.172138.5c52b25283a-x86_64-linux.iso.sha256 | shasum [--algorithm -a] 256 [--check -c]

2. Booting the system

Write NixOS on your USB stick (be careful, it’s /dev/sdb in my case).

dd if=nixos-graphical-19.03.172138.5c52b25283a-x86_64-linux.iso of=/dev/sdb

Boot NixOS then you’re ready for the next step.

3. Partitioning and formatting

Wipe the file system:

wipefs [--all -a] /dev/sda

Option 1: GParted

Create the partitions, formats and labels:

gparted

You can use GParted or gdisk, but I recommend GParted for discoverability.

1. Create a GUID table: Device ❯ Create Partition Table ❯ GPT

• Select /dev/sda
• Entire disk

2. Create the boot partition: Partition ❯ New

• Free space preceding (MiB): 1 (You cannot less; space assigned to GPT)
• New size (MiB): 512
• Free space following (MiB): Rest
• Align to: MiB
• Create as: Primary Partition
• Partition name: EFI
• File system: fat32
• Label: EFI

3. Add the boot flag

• Right-click on /dev/sda1 to manage flags
• Add the boot flag and enable esp (should be automatic with GPT)

4. Create the root partition: Partition ❯ New

• Free space preceding (MiB): 0
• New size (MiB): Rest
• Free space following (MiB): 0
• Align to: MiB
• Create as: Primary Partition
• Partition name: NixOS
• File system: ext4
• Label: NixOS

5. Apply modifications

Option 2: GPT fdisk

Create the partitions:

gdisk /dev/sda
# GUID table:
# Press 'o' to create a new empty GUID partition table (GPT)
# Boot (EFI):
# Press 'n' for new partition
# – Partition number: 1 – should be default
# – First sector: Use default
# – Last sector: +512M
# – Hex code: ef00 (EFI system partition)
# Press 'c' to change partition’s name
# – Partition number: 1
# – Partition name: EFI
# Root:
# Press 'n' for new partition
# – Partition number: 2 – should be default
# – First sector: Use default
# – Last sector: Use default
# – Hex code: 8300 (Linux filesystem) – should be default
# Press 'c' to change partition’s name
# – Partition number: 2
# – Partition name: NixOS
# Press 'w' to write table to disk and exit

Format and label the file systems for each partition:

mkfs.fat -F 32 /dev/sda1 -n EFI # Boot (EFI)
fatlabel /dev/sda1 EFI # Optional, to label a FAT disk after its creation
mkfs.ext4 /dev/sda2 -L NixOS # Root
e2label /dev/sda2 NixOS # Optional, to label an ext disk after its creation

Note: Many partitioning tools do not create filesystems; they just create the partitions in which filesystems can be created. To create a filesystem, you need to use commands such as mkfs.

4. Installing

Mount the root and boot partitions:

mkdir /mnt/nixos
mount /dev/disk/by-label/NixOS /mnt/nixos
mkdir /mnt/nixos/boot
mount /dev/disk/by-label/EFI /mnt/nixos/boot

Generate an initial configuration:

nixos-generate-config --root /mnt/nixos
# /etc/nixos/configuration.nix
# /etc/nixos/hardware-configuration.nix

Do the installation:

nixos-install --root /mnt/nixos

If everything went well:

reboot

5. Changing the Configuration

The file /etc/nixos/configuration.nix contains the current configuration of your machine. Whenever you’ve changed something in that file, you should do nixos-rebuild switch to switch to the new configuration.

nixos-rebuild switch

Warning: These commands must be executed as root, so you should either run them from a root shell or by prefixing them with sudo [--login -i].

You can check my configuration here.

Packages

nix search [package]

Options

man configuration.nix

6. Upgrading NixOS

When you first install NixOS, you’re automatically subscribed to the NixOS channel that corresponds to your installation source. For instance, if you installed from a 19.03 ISO, you will be subscribed to the nixos-19.03 channel. To see which NixOS channel you’re subscribed to, run the following as root:

nix-channel --list
# nixos https://nixos.org/channels/nixos-19.03

If you want to live on the bleeding edge:

nix-channel --add https://nixos.org/channels/nixos-unstable nixos

To upgrade NixOS:

nixos-rebuild switch --upgrade

The command is equivalent to the more verbose:

nix-channel --update
nixos-rebuild switch

7. Cleaning the Nix Store

nix-collect-garbage [--delete-old -d]

8. Package Management

Customising Packages

See also:

• Overlays
• Modify packages via packageOverrides

Adding Custom Packages

9. Developing

Support for specific programming languages and frameworks

I installed a library but my compiler is not finding it. Why?

Command-line:

nix-shell [--packages -p] pkg-config rustc cargo

Using default.nix or shell.nix:

with import <nixpkgs> {};

mkShell {
  buildInputs = [
    pkg-config
    rustc
    cargo
  ];
}

nix-shell

pkgs.mkShell is a simplified version of stdenv.mkDerivation:

with import <nixpkgs> {};

stdenv.mkDerivation {
  name = "dev-environment";
  buildInputs = [
    pkg-config
    rustc
    cargo
  ];
}

You can see its definition on GitHub.

I’m working on a new package, how can I build it without adding it to nixpkgs?

Assuming your package name is default.nix:

nix build '(
  with import <nixpkgs> {};
  callPackage ./default.nix {}
)'
# result → /nix/store/{hash}-{name}-{version}

10. FAQ