Posted on (↻ ).


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

Create the partitions, formats and labels:


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

  1. Create a GUID table: DeviceCreate Partition TableGPT
    • Select /dev/sda
    • Entire disk
  2. Create the boot partition: PartitionNew
    • 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: PartitionNew
    • 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

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:


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.


nix search [package]


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

If you want to live on the bleeding edge:

nix-channel --add 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:

Adding Custom Packages

9. Developing

Support for specific programming languages and frameworks

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


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

Using default.nix or shell.nix:

with import <nixpkgs> {};

mkShell {
  buildInputs = [

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

with import <nixpkgs> {};

stdenv.mkDerivation {
  name = "dev-environment";
  buildInputs = [

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