NixOS Installation Guide

From NixOS Wiki
Revision as of 23:23, 25 November 2017 by imported>Samueldr (Removed last of outdated marks)

This guide is a companion guide for the official manual. In addition to describing 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.

Use this guide as a step-by-step guide, choices will be presented, use only the selected section, and continue at the section it tells you to at the end.

Installation target

NixOS can be installed on an increasing variety of hardware, including the usual x86-type hardware.

  1. A regular (Intel or AMD) desktop computer, laptop, or physically accessible server can follow the instructions in this page
  2. SBCs, like the Raspberry Pis, and other ARM boards can follow the instructions at NixOS on ARM
  3. Cloud and remote servers will find various instructions at NixOS friendly hosters

Installation method

NixOS, as with most Linux-based operating systems, can be installed in different ways.

  1. The classic way, booting from the installation media (described in this page)
  2. 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

  1. Find the right device with lsblk or fdisk -l. Replace /dev/sdX with the proper device in the following steps.
  2. Burn with: cp nixos-xxx.iso /dev/sdX
Note: do not use /dev/sdX1 or partitions of the disk, use the whole disk /dev/sdX.

Writing the disk image with dd also works.

From macOS

Template:Outdated:inline

  1. Find the right device with diskutil list, let's say diskX.
  2. Unmount with diskutil unmountDisk diskX.
  3. Burn with: sudo dd if=path_to_nixos.iso of=/dev/rdiskX bs=64k
Note: Use rdisk instead of disk, this makes a large speed difference. You can check the write speed with iostat 2 in another terminal.

You could use Disk Utility to write the image but then you'd need to convert it first to a compatible format somehow.

From Windows

Template:Outdated:inline

  1. Download USBwriter.
  2. Start USBwriter.
  3. Choose the downloaded ISO as 'Source'
  4. Choose the USB drive as 'Target'
  5. Click 'Write'
  6. 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.

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.