NixOS Installation Guide: Difference between revisions

(35 intermediate revisions by 19 users not shown)

Line 1:

This guide is a companion guide for the [https://nixos.org/nixos/manual/index.html#ch-installation 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~~.

This guide is a companion guide for the [https://nixos.org/nixos/manual/index.html#ch-installation official manual]. It describes installation of [[NixOS]] as a complete operating system. For installation of [[Nix]] within an existing operating system, see [[Nix Installation Guide]].

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 ==

== Installation target ==

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

NixOS can be installed on an increasing variety of hardware:

~~# A~~ regular (Intel or AMD) desktop ~~computer, laptop~~, or physically accessible ~~server can follow the instructions in~~ this page

~~# [[NixOS on ARM|~~SBCs, like the Raspberry Pis, and other ARM boards ~~can follow the instructions at ''~~NixOS on ARM'']]

* regular (Intel or AMD) desktop computers, laptops or physically accessible servers, covered on this page

~~# [[NixOS friendly hosters|Cloud~~ and remote servers ~~will find various instructions at ''~~NixOS friendly hosters'']]

* SBCs (like the Raspberry Pis) and other ARM boards, see [[NixOS on ARM]]

* cloud and remote servers, see [[NixOS friendly hosters]]

== Installation method ==

== Installation method ==

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

# ~~[[#Installing from the installation media|~~The classic way, booting from the installation media (~~described in this page~~)]]

# The classic way, booting from the installation media. (Described below.)

# [[Installing from Linux|Booting the media from an existing Linux installation]]

== Making the installation media ==

== 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 ===

=== "Burning" to USB drive ===

First, download a [https://nixos.org~~/nixos~~/download.html NixOS ISO image] or [[Creating a NixOS live CD|create a custom ISO]]. Then plug in a USB stick large enough to accommodate the image. Then follow the platform instructions:

First, download a [https://nixos.org/download.html#nixos-iso NixOS ISO image] or [[Creating a NixOS live CD|create a custom ISO]]. Then plug in a USB stick large enough to accommodate the image. Then follow the platform instructions:

==== From Linux ====

==== From Linux ====

# Find the right device with <code>lsblk</code> or <code>fdisk -l</code>. Replace <code>/dev/sdX</code> with the proper device in the following steps.

# ~~Burn with~~: <code>cp nixos-xxx.iso /dev/sdX</code>

# Copy to device: <code>cp nixos-xxx.iso /dev/sdX</code>

{{note|do not use /dev/sdX1 or partitions of the disk, use the whole disk /dev/sdX.}}

Writing the disk image with <code>dd</code> also works.

Writing the disk image with <code>dd if=nixos.iso of=/dev/sdX bs=4M status=progress conv=fdatasync</code> also works.

==== From macOS ====

==== From macOS ====

~~{{outdated~~:~~inline|Instructions are not verified to be working as of 2017~~-11-~~25, it is most likely they work, please remove this warning when tested.}}~~

# Find the right device with <code>diskutil list</code>, let's say <code>diskX</code>.

# Unmount with <code>diskutil unmountDisk diskX</code>.

# Burn with: <code>sudo dd if=path_to_nixos.iso of=/dev/~~r~~diskX ~~bs=64k</code>~~

# Burn with: <code>sudo dd if=path_to_nixos.iso of=/dev/diskX</code>

~~{{note|Use <code>rdisk</code> instead of <code>disk</code>, this makes a large speed difference. You can check the write speed with <code>iostat 2~~</code> ~~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~~.

{{tip|Using <code>rdiskX</code> instead of <code>diskX</code> can makes a large speed difference. You can check the write speed with <code>iostat 2</code> in another terminal.}}

==== From Windows ====

==== From Windows ====

~~{{outdated~~:~~inline|Instructions are not verified to be working as of 2017~~-11-~~25, it is most likely they work, please remove this warning when tested.}}~~

# Download [http://sourceforge.net/projects/usbwriter/ USBwriter].

# Start USBwriter.

Line 56:

Line 71:

# When USBwriter has finished writing, safely unplug the USB drive.

=== Alternative installation media instructions ===

=== 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.

* [[NixOS_Installation_Guide/Unetbootin|Using Unetbootin]]

* [[NixOS_Installation_Guide/Manual USB Creation|Manual USB Creation]]

* [[NixOS_Installation_Guide/multibootusb|multibootusb]]

== Booting the installation media ==

Since the installation media is hybrid, it will boot both in 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 ===

=== Legacy bios boot ===

This is the only boot possible on machines lacking EFI/UEFI.

=== UEFI boot ===

=== 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 ===

Network Manager is installed on the graphical ISO, meaning that it is possible to use <code>nmtui</code> 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 <code>nmtui</code>. 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 <code>wpa_supplicant</code> then you can also run <code>wpa_passphrase ESSID | sudo tee /etc/wpa_supplicant.conf</code>, then enter your password and <code>systemctl restart wpa_supplicant</code>.

== Partitioning ==

To partition the persistent storage run <code>sudo fdisk /dev/diskX</code> and follow instructions for DOS or (U)EFI.

A very simple example setup is given here.

=== DOS ===

* 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)

* 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)

* w (write)

== Label partitions ==

This is useful for having multiple setups and makes partitions easier to handle<syntaxhighlight lang="console">

$ lsblk

$ sudo mkfs.fat -F 32 /dev/sdX1

$ sudo fatlabel /dev/sdX1 NIXBOOT

$ sudo mkfs.ext4 /dev/sdX2 -L NIXROOT

$ sudo mount /dev/disk/by-label/NIXROOT /mnt

$ sudo mkdir -p /mnt/boot

$ sudo mount /dev/disk/by-label/NIXBOOT /mnt/boot

</syntaxhighlight>

== Swap file ==

$ sudo dd if=/dev/zero of=/mnt/.swapfile bs=1024 count=2097152 (2GB size)

$ sudo chmod 600 /mnt/.swapfile

$ sudo mkswap /mnt/.swapfile

$ sudo swapon /mnt/.swapfile

</syntaxhighlight>

== NixOS config ==

$ sudo nixos-generate-config --root /mnt

$ cd /mnt/etc/nixos/

$ sudo vim configuration.nix

</syntaxhighlight>Most essential changes:

* keyboard layout, ie <code>[[Keyboard Layout Customization|services.xserver.xkb.layout]]</code>

* <code>users.users.user</code> with adding entry <code>initialPassword = "pw123";</code>

* [[networking]] (wifi), see below for fix if it breaks

* <code>boot.loader.grub.device = "/dev/sda"; #or "nodev" for efi only</code>

* install editor to edit the configuration

* change hardware config to use labels

The self-documenting NixOS options can be searched with [https://search.nixos.org/options NixOS options search].

== NixOS installation ==

$ cd /mnt

$ sudo nixos-install

</syntaxhighlight>after installation: Run <code>passwd</code> to change user password.

if internet broke/breaks, try one of the following:<syntaxhighlight lang="console">

$ nixos-rebuild switch --option substitute false # no downloads

$ nixos-rebuild switch --option binary-caches "" # no downloads

</syntaxhighlight>

* wpa_supplicant flags to connect to wifi

<hr />

== Additional notes for specific hardware ==

== Additional notes for specific hardware ==

These are collected notes or links for specific hardware issues.

* Blog post how to install NixOS on a [http://grahamc.com/blog/nixos-on-dell-9560 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.

* Brand servers may require extra kernel modules be included into initrd (<code>boot.initrd.extraKernelModules</code> in configuration.nix) For example HP Proliant needs "hpsa" module to see the disk drive.

[[Category:Guide]][[Category:~~Installation~~]]

[[Category:Guide]][[Category:Deployment]]

</translate>

@@ Line 1: / Line 1: @@
-This guide is a companion guide for the [https://nixos.org/nixos/manual/index.html#ch-installation 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.
+<languages/>
+<translate>
+<!--T:1-->
+This guide is a companion guide for the [https://nixos.org/nixos/manual/index.html#ch-installation official manual]. It describes installation of [[NixOS]] as a complete operating system. For installation of [[Nix]] within an existing operating system, see [[Nix Installation Guide]].
+<!--T:2-->
+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.
+<!--T:3-->
 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 ==
+== Installation target == <!--T:4-->
-NixOS can be installed on an increasing variety of hardware, including the usual x86-type hardware.
+<!--T:5-->
+NixOS can be installed on an increasing variety of hardware:
-# A regular (Intel or AMD) desktop computer, laptop, or physically accessible server can follow the instructions in this page
+<!--T:6-->
-# [[NixOS on ARM|SBCs, like the Raspberry Pis, and other ARM boards can follow the instructions at ''NixOS on ARM'']]
+* regular (Intel or AMD) desktop computers, laptops or physically accessible servers, covered on this page
-# [[NixOS friendly hosters|Cloud and remote servers will find various instructions at ''NixOS friendly hosters'']]
+* SBCs (like the Raspberry Pis) and other ARM boards, see [[NixOS on ARM]]
+* cloud and remote servers, see [[NixOS friendly hosters]]
-== Installation method ==
+== Installation method == <!--T:7-->
+<!--T:8-->
 NixOS, as with most Linux-based operating systems, can be installed in different ways.
-# [[#Installing from the installation media|The classic way, booting from the installation media (described in this page)]]
+<!--T:9-->
+# The classic way, booting from the installation media. (Described below.)
 # [[Installing from Linux|Booting the media from an existing Linux installation]]
-== Making the installation media ==
+== Making the installation media == <!--T:10-->
+<!--T:11-->
 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 ===
+=== "Burning" to USB drive === <!--T:12-->
-First, download a [https://nixos.org/nixos/download.html NixOS ISO image] or [[Creating a NixOS live CD|create a custom ISO]]. Then plug in a USB stick large enough to accommodate the image. Then follow the platform instructions:
+<!--T:13-->
+First, download a [https://nixos.org/download.html#nixos-iso NixOS ISO image] or [[Creating a NixOS live CD|create a custom ISO]]. Then plug in a USB stick large enough to accommodate the image. Then follow the platform instructions:
-==== From Linux ====
+==== From Linux ==== <!--T:14-->
+<!--T:15-->
 # Find the right device with <code>lsblk</code> or <code>fdisk -l</code>. Replace <code><i>/dev/sdX</i></code> with the proper device in the following steps.
-# Burn with: <code>cp nixos-xxx.iso <em>/dev/sdX</em></code>
+# Copy to device: <code>cp nixos-xxx.iso <em>/dev/sdX</em></code>
+<!--T:16-->
 {{note|do not use /dev/sdX1 or partitions of the disk, use the whole disk /dev/sdX.}}
-Writing the disk image with <code>dd</code> also works.
+<!--T:17-->
+Writing the disk image with <code>dd if=nixos.iso of=/dev/sdX bs=4M status=progress conv=fdatasync</code> also works.
-==== From macOS ====
+==== From macOS ==== <!--T:18-->
-{{outdated:inline|Instructions are not verified to be working as of 2017-11-25, it is most likely they work, please remove this warning when tested.}}
+<!--T:19-->
 # Find the right device with <code>diskutil list</code>, let's say <code><i>diskX</i></code>.
 # Unmount with <code>diskutil unmountDisk <i>diskX</i></code>.
-# Burn with: <code>sudo dd if=<b>path_to_nixos.iso</b> of=/dev/<b>r</b><i>diskX</i> bs=64k</code>
+# Burn with: <code>sudo dd if=<b>path_to_nixos.iso</b> of=/dev/<i>diskX</i></code>
-{{note|Use <code>rdisk</code> instead of <code>disk</code>, this makes a large speed difference. You can check the write speed with <code>iostat 2</code> 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.
+<!--T:20-->
+{{tip|Using <code>rdiskX</code> instead of <code>diskX</code> can makes a large speed difference. You can check the write speed with <code>iostat 2</code> in another terminal.}}
-==== From Windows ====
+==== From Windows ==== <!--T:21-->
-{{outdated:inline|Instructions are not verified to be working as of 2017-11-25, it is most likely they work, please remove this warning when tested.}}
+<!--T:22-->
 # Download [http://sourceforge.net/projects/usbwriter/ USBwriter].
 # Start USBwriter.
@@ Line 56: / Line 71: @@
 # When USBwriter has finished writing, safely unplug the USB drive.
-=== Alternative installation media instructions ===
+=== Alternative installation media instructions === <!--T:23-->
+<!--T:24-->
 The previous methods are the supported methods of making the USB installation media.
+<!--T:25-->
 Those methods are also documented, they can allow using the USB drive to boot multiple distributions. This is not supported, your mileage may vary.
+<!--T:26-->
 * [[NixOS_Installation_Guide/Unetbootin|Using Unetbootin]]
 * [[NixOS_Installation_Guide/Manual USB Creation|Manual USB Creation]]
+* [[NixOS_Installation_Guide/multibootusb|multibootusb]]
+<!--T:27-->
 == Booting the installation media ==
 {{expansion|Troubleshooting steps, and details are lacking.}}
+<!--T:28-->
 Since the installation media is hybrid, it will boot both in legacy bios mode and UEFI mode.
+<!--T:29-->
 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 ===
+=== Legacy bios boot === <!--T:30-->
+<!--T:31-->
 This is the only boot possible on machines lacking EFI/UEFI.
-=== UEFI boot ===
+=== UEFI boot === <!--T:32-->
+<!--T:33-->
 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 == <!--T:34-->
+<!--T:35-->
+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 === <!--T:36-->
+<!--T:37-->
+For network interfaces supported by the kernel, DHCP resolution should already have happened once the shell is available.
+==Tethered (Internet Sharing)== <!--T:38-->
+<!--T:39-->
+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 === <!--T:40-->
+<!--T:41-->
+Network Manager is installed on the graphical ISO, meaning that it is possible to use <code>nmtui</code> on the command line to connect to a network.
+<!--T:42-->
+Using the "Applications" tab at top
+left or the launcher bar at bottom, choose a terminal application and from there launch <code>nmtui</code>. 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.
+<!--T:43-->
+On the minimal ISO, or if you are more familiar with <code>wpa_supplicant</code> then you can also run <code>wpa_passphrase ESSID | sudo tee /etc/wpa_supplicant.conf</code>, then enter your password and <code>systemctl restart wpa_supplicant</code>.
+== Partitioning == <!--T:44-->
+<!--T:45-->
+To partition the persistent storage run <code>sudo fdisk /dev/diskX</code> and follow instructions for DOS or (U)EFI.
+A very simple example setup is given here.
+=== DOS === <!--T:46-->
+<!--T:47-->
+* 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 === <!--T:48-->
+<!--T:49-->
+* 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)
+== Label partitions == <!--T:50-->
+<!--T:51-->
+This is useful for having multiple setups and makes partitions easier to handle<syntaxhighlight lang="console">
+$ lsblk
+$ sudo mkfs.fat -F 32 /dev/sdX1
+$ sudo fatlabel /dev/sdX1 NIXBOOT
+$ sudo mkfs.ext4 /dev/sdX2 -L NIXROOT
+$ sudo mount /dev/disk/by-label/NIXROOT /mnt
+$ sudo mkdir -p /mnt/boot
+$ sudo mount /dev/disk/by-label/NIXBOOT /mnt/boot
+</syntaxhighlight>
+<!--T:52-->
+== Swap file ==
+<syntaxhighlight lang="console">
+$ sudo dd if=/dev/zero of=/mnt/.swapfile bs=1024 count=2097152 (2GB size)
+$ sudo chmod 600 /mnt/.swapfile
+$ sudo mkswap /mnt/.swapfile
+$ sudo swapon /mnt/.swapfile
+</syntaxhighlight>
+<!--T:53-->
+== NixOS config ==
+<syntaxhighlight lang="console">
+$ sudo nixos-generate-config --root /mnt
+$ cd /mnt/etc/nixos/
+$ sudo vim configuration.nix
+</syntaxhighlight>Most essential changes:
+<!--T:54-->
+* keyboard layout, ie <code>[[Keyboard Layout Customization|services.xserver.xkb.layout]]</code>
+* <code>users.users.user</code> with adding entry <code>initialPassword = "pw123";</code>
+* [[networking]] (wifi), see below for fix if it breaks
+* <code>boot.loader.grub.device = "/dev/sda"; #or "nodev" for efi only</code>
+* install editor to edit the configuration
+* change hardware config to use labels
+<!--T:55-->
+The self-documenting NixOS options can be searched with [https://search.nixos.org/options NixOS options search].
+<!--T:56-->
+== NixOS installation ==
+<syntaxhighlight lang="console">
+$ cd /mnt
+$ sudo nixos-install
+</syntaxhighlight>after installation: Run <code>passwd</code> to change user password.
+<!--T:57-->
+if internet broke/breaks, try one of the following:<syntaxhighlight lang="console">
+$ nixos-rebuild switch --option substitute false # no downloads
+$ nixos-rebuild switch --option binary-caches "" # no downloads
+</syntaxhighlight>
+* wpa_supplicant flags to connect to wifi
+<!--T:58-->
 <hr />
-== Additional notes for specific hardware ==
+== Additional notes for specific hardware == <!--T:59-->
+<!--T:60-->
 These are collected notes or links for specific hardware issues.
+<!--T:61-->
 * Blog post how to install NixOS on a [http://grahamc.com/blog/nixos-on-dell-9560 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.
+* Brand servers may require extra kernel modules be included into initrd (<code>boot.initrd.extraKernelModules</code> in configuration.nix) For example HP Proliant needs "hpsa" module to see the disk drive.
-[[Category:Guide]][[Category:Installation]]
+<!--T:62-->
+[[Category:Guide]][[Category:Deployment]]
+</translate>