Jump to content

NixOS Installation Guide: Difference between revisions

From NixOS Wiki
← Older edit
VisualWikitext
imported>Samueldr
m →Using Unetbootin: moves instructions to a standalone page
Pigeon (talk | contribs)
12 edits
m fix typo in #Custom_configuration
 
(46 intermediate revisions by 23 users not shown)
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 serves as 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 instructions on installing [[Nix]] within an existing operating system, refer to the [[Nix Installation Guide]].


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.
<!--T:2-->
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 ==
== 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.
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]]
# [[Installing from Linux|Booting the media from an existing Linux installation]]


== Making the installation media == <!--T:10-->


{{outdated|Starting from here, the installation guide haven't been revised yet.}}
<!--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.


== Making the installation media ==
=== "Burning" to USB drive === <!--T:12-->


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 Mac* systems. Please read the [[#Hybrid image]] section on how to burn the ISO.
<!--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:


For NixOS 14.04 and earlier, please read [[#Using Unetbootin]] and the other sections below.
==== From Linux ==== <!--T:14-->


=== Hybrid image ===
<!--T:15-->
{{Note|This section applies to NixOS 14.11. For NixOS 14.04, please refer to [[#Using Unetbootin]].}}
# 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.
# Copy to device: <code>cp nixos-xxx.iso <em>/dev/sdX</em></code>


First, download a [http://nixos.org/nixos/download.html NixOS ISO image] or [[Creating a Nix OS live CD|create a custom ISO]]. Then plug in a USB stick large enough to accomodate the image. Then follow the platform instructions:
<!--T:16-->
{{note|do not use /dev/sdX1 or partitions of the disk, use the whole disk /dev/sdX.}}


On Linux:
<!--T:17-->
# Find the right device with <code>fdisk -l</code>, let's say <code>/dev/sdb</code>.
Writing the disk image with <code>dd if=nixos.iso of=/dev/sdX bs=4M status=progress conv=fdatasync</code> also works.
# Burn with: <code>cp nixos-xxx.iso /dev/sdb</code>
{{Note|do not use /dev/sdb1 or partitions of the disk, use the whole disk /dev/sdb.}}


On OS X:
==== From macOS ==== <!--T:18-->
# Find the right device with <code>diskutil list</code>, let's say <code>disk<b>2</b></code>.
# Unmount with <code>diskutil unmountDisk disk<b>2</b></code>.
# Burn with: <code>sudo dd if=<b>path_to_nixos.iso</b> of=/dev/<b>r</b>disk<b>2</b> bs=64k</code>
# Note the use of rdisk instead of disk, 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: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/<i>diskX</i></code>


On Windows:
<!--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 ==== <!--T:21-->
 
<!--T:22-->
# Download [http://sourceforge.net/projects/usbwriter/ USBwriter].
# Download [http://sourceforge.net/projects/usbwriter/ USBwriter].
# Start USBwriter.
# Start USBwriter.
Line 53: Line 68:
# When USBwriter has finished writing, safely unplug the USB drive.
# When USBwriter has finished writing, safely unplug the USB drive.


This should suffice to boot the installer. Otherwise look for other alternatives below.
=== Alternative installation media instructions === <!--T:23-->
 
<!--T:24-->
The previous methods are the supported methods of making the USB installation media.


=== UEFI note ===
<!--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.


The below is for BIOS installation. For UEFI installation see [http://nixos.org/nixos/manual/#sec-uefi-installation the manual].
<!--T:26-->
* [[NixOS_Installation_Guide/Unetbootin|Using Unetbootin]]
* [[NixOS_Installation_Guide/Manual USB Creation|Manual USB Creation]]
* [[NixOS_Installation_Guide/multibootusb|multibootusb]]


=== Using Unetbootin ===
<!--T:27-->
== Booting the installation media ==
{{expansion|Troubleshooting steps, and details are lacking.}}


See → [NixOS_Installation_Guide/Unetbootin]
<!--T:28-->
The installation media is hybrid and is capable of booting in both legacy BIOS mode and [[UEFI]] mode.


=== Using syslinux ===
<!--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.


==== Using syslinux.cfg ====
=== Legacy bios boot === <!--T:30-->


If you have trouble booting from a USB drive or sdcard with Unetbootin (I just got a blinking cursor instead of a bootloader on an Asus eee 1000) the procedure described on http://knoppix.net/wiki/Bootable_USB_Key should work. After preparing the sdcard with mkdiskimage and syslinux you can mount it and copy all the content from the NixOS iso:
<!--T:31-->
This is the only boot possible on machines lacking EFI/UEFI.
 
=== 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-->
[[NetworkManager]] 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 [[wpa_supplicant]] 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 MBR or (U)EFI. To determine which mode you are booted into, run:


<syntaxhighlight lang="console">
<syntaxhighlight lang="console">
$ mount -o loop ~/Downloads/nixos-graphical-0.1pre27337-i686-linux.iso /media/iso
$ [ -d /sys/firmware/efi/efivars ] && echo "UEFI" || echo "Legacy"
$ rsync -av --progress /media/iso/ /media/sd-card/
</syntaxhighlight>
</syntaxhighlight>


The syslinux.cfg needs to be created manually, but the details can easily be derived from the grub.cfg on the NixOS install cd.


I specified the root device by UUID, to get the UUID:
A very simple example setup is given here.


<pre>
=== Legacy Boot (MBR) === <!--T:46-->
blkid /dev/mmcblk0p1
</pre>


The relevant section from the live cd: /media/sd-card/boot/grub/grub.cfg
<!--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)


<pre>
=== UEFI === <!--T:48-->
menuentry "NixOS Installer / Rescue" {
  linux /boot/bzImage init=/nix/store/r7xhnzymi1ll49r4glf1dwr5y1alx0bl-system/init root=LABEL=NIXOS_INSTALL_CD_0.1pre27337 splash=verbose vga=0x317
  initrd /boot/initrd
}
</pre>


can be used in the syslinux config file: /media/sd-card/syslinux.cfg (you should just need to update the init path and the root UUID / LABEL or device path)
<!--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)


<pre>
=== Format partitions === <!--T:50-->
DEFAULT linux
LABEL linux
  SAY Now booting the kernel from SYSLINUX...
  KERNEL /boot/bzImage
  APPEND init=/nix/store/r7xhnzymi1ll49r4glf1dwr5y1alx0bl-system/init root=UUID=509C-63E2 ro initrd=/boot/initrd splash=verbose
</pre>


'''Note''': in place of using mkdiskimage, you can simply format your SDCard as a fat32 system and install syslinux on it:
<!--T:51-->
The example below uses the [[ext4]] filesystem format. If you wish to use other filesystem formats such as [[Btrfs]] or [[ZFS]]:  


<pre>
* [[Bcachefs#NixOS installation on bcachefs]]
mkdosfs -F32 /dev/mmcblk0p1
* [[Btrfs#Installation of NixOS on btrfs]]
syslinux -s /dev/mmcblk0p1
* [[LVM#Basic Setup]]
</pre>
* [[ZFS#Simple NixOS ZFS on root installation]]


=== Using Command-line Tools ===
This is useful for having multiple setups and makes partitions easier to handle<syntaxhighlight lang="console">
$ 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/nixos /mnt
# mkdir -p /mnt/boot
# mount /dev/disk/by-label/boot /mnt/boot
</syntaxhighlight>


<ol>
<!--T:53-->
<li>Download the ISO image from http://nixos.org/nixos/download.html.</li>
== NixOS configuration ==


<li>Prepare your USB stick. If it isn't yet partitioned to your liking, create a bootable partition on <code>/dev/sdb1</code>:
NixOS is configured through a [[Overview of the NixOS Linux distribution#Declarative Configuration|declarative configuration]] file. To generate a default config file, run [[nixos-generate-config]]:


<pre>
<syntaxhighlight lang="console">
fdisk /dev/sdb
# nixos-generate-config --root /mnt
</pre>
# nano /mnt/etc/nixos/configuration.nix
</syntaxhighlight>


And format it with:
For information on working with a system configuration, see [[NixOS system configuration]]. For desktop-specific configurations, see [[NixOS as a desktop]].


<pre>
Most essential changes:
mkdosfs /dev/sdb1
</pre>


Add ext2 partitions if you like. If you want both 32-bit and 64-bit NixOS, you need at least two partitions. You can directly use the entire disk without partition if that's what you like. Once you have your VFAT (dosfs) block device, you should give it a label, within a 11-character limit, e.g.:
<!--T:54-->
* keyboard layout, ie <code>[[Keyboard Layout Customization|services.xserver.xkb.layout]]</code>
* [[networking]] (wifi), see below for fix if it breaks
* install [[:Category:Text Editor|editor]] to edit the configuration


<pre>
<!--T:55-->
dosfslabel /dev/sdb1 NIXBOOT
The self-documenting NixOS options can be searched with [https://search.nixos.org/options NixOS options search].
</pre>
</li>


<li>Mount the bootable USB partition with:
<!--T:52-->
=== Swap file ===


<pre>
For additional methods of configuring swap, see [[Swap]]. The following example demonstrates how to create and enable a [[Swap#Swap file|swap file]]:
mkdir -p /media/NIXBOOT
mount /dev/sdb1 /media/NIXBOOT
</pre>
</li>


<li>Mount the ISO image with:
{{file|/mnt/etc/nixos/configuration.nix|nix|
<nowiki>
  swapDevices = [{
    device = "/var/lib/swapfile";
    size = 16*1024; # 16 GB
  }];
</nowiki>
}}


<pre>
=== Bootloader ===
mkdir -p /media/iso
mount -o loop ~/Downloads/nixos-graphical-0.2pre4463_5e88e9b-c877f45-x86_64-linux.iso /media/iso
</pre>
</li>


<li>Copy the contents of the NixOS ISO (<code>/media/iso</code>) to your USB stick (<code>/media/NIXBOOT</code>) with:
NixOS supports multiple [[Bootloader|bootloaders]] such as [[GNU GRUB]] and [[Systemd/boot]].


<pre>
Systemd-boot is the recommended bootloader. The following example demonstrates how to enable systemd-boot in your configuration:
rsync -av --progress /media/iso/ /media/NIXBOOT/
</pre>
</li>


<li>Install a complete and recent GRUB to the USB stick with:
{{file|/mnt/etc/nixos/configuration.nix|nix|
<nowiki>
  boot.loader.systemd-boot.enable = true;
</nowiki>
}}


<pre>
You may also wish to configure [[Secure Boot]].
grub-install /dev/sdb --root-directory=/media/NIXBOOT/
</pre>
</li>


<li>Edit the file <code>/media/NIXBOOT/boot/grub/grub.cfg</code>. Start from an existing grub.cfg, say from your hard drive or from another working bootable USB stick (e.g., from GRML.org). Then, merge in the entry for NixOS from <code>/media/iso/boot/grub/grub.cfg</code>, modifying the LABEL to be that of your VFAT partition:
=== Users ===


<pre>
For information on creating and managing users, see [[User management]] and the {{NixOS Manual|name=NixOS Manual: Chapter - Package Management|anchor=#sec-user-management}}. See an example below:
menuentry "NixOS Installer / Rescue" {
  linux /boot/bzImage init=/nix/store/p94ckcksmhj90cr868cpcajrqgzwy57w-nixos-0.2pre4463_5e88e9b-c877f45/init root=LABEL=NIXBOOT
  initrd /boot/initrd
}
</pre>
</li>


<li>To share your USB stick with other distributions (e.g., GRML, or both 32- and 64- bit NixOS), you can move NixOS's bzImage and initrd to different location (e.g., <code>/boot/nix32/</code> and <code>/boot/nix64/</code>), and you appropriately edit the entries in your grub.cfg. If you have both nix32 and nix64, only one can have its <code>nix-store.squashfs</code> in the root of any given partition.  That's where you can use a second partition, for the second one.  For instance, copy the contents of your 64-bit NixOS to the first partition, with label <code>NIX64</code>, and copy the nix-store.squashfs of your 32-bit NixOS to the second partition with label <code>NIX32</code> (and create an empty nix/store). Copy the 32-bit kernel and initrd to <code>/boot/nix32/</code> on the bootable partition, and edit the grub.cfg of the bootable partition accordingly.</li>
{{file|/mnt/etc/nixos/configuration.nix|nix|
<nowiki>
  users.users.alice = {
    isNormalUser = true;
    initialPassword = "pw123";
  };
</nowiki>
}}


<li>There you go: you have a bootable NixOS USB drive, possibly allowing you to boot NixOS 64-bit, NixOS 32-bit, GRML 64-bit, GRML 32-bit, FreeBSD, FreeDOS, boot-sector-tetris, etc. Just you convince your BIOS to let you boot off it.</li>
== NixOS installation ==
</ol>
<syntaxhighlight lang="console">
# cd /mnt
# nixos-install
</syntaxhighlight>after installation: Run <code>passwd</code> to change user password.


== Build a custom installation image ==
<!--T:57-->
 
if internet broke/breaks, try one of the following:<syntaxhighlight lang="console">
NixOS provides an easy way to build a custom variant of the installation image. This might be useful to embed your own ssh key or enable additional features like zfs support. It allows to specify a custom <code>configuration.nix</code> which is used to build the image
# nixos-rebuild switch --option substitute false # no downloads
This is explained in [[Creating a NixOS live CD]].
# nixos-rebuild switch --option binary-caches "" # no downloads
</syntaxhighlight>
* wpa_supplicant flags to connect to wifi


== Installing on VPS & Cloud Providers ==
<!--T:58-->
<hr />


→ See [[NixOS friendly hosters]]
== Additional notes for specific hardware == <!--T:59-->


== Special hardware ==
<!--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]
* Blog post how to install NixOS on a [http://grahamc.com/blog/nixos-on-dell-9560 Dell 9560]
* for embedded Hardware like the Raspberry Pi2 see [[NixOS on ARM]]
* 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.
* 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.
 


<!--T:62-->
[[Category:Guide]]
[[Category:Guide]]
 
[[Category:Deployment]]
[[Category:Installation]]
[[Category:NixOS]]
</translate>

Latest revision as of 16:50, 20 August 2025

Other languages:

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.

  1. The classic way, booting from the installation media. (Described below.)
  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. Copy to device: 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 if=nixos.iso of=/dev/sdX bs=4M status=progress conv=fdatasync also works.

From macOS

  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/diskX
🟆︎
Tip: Using rdiskX instead of diskX can makes a large speed difference. You can check the write speed with iostat 2 in another terminal.

From Windows

  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.

Booting the installation media

☶︎
This article or section needs to be expanded. Further information may be found in the related discussion page. Please consult the pedia article metapage for guidelines on contributing.

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:

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/nixos /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

For information on working with a system configuration, see NixOS system configuration. For desktop-specific configurations, see NixOS as a desktop.

Most essential changes:

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:

❄︎ /mnt/etc/nixos/configuration.nix
  swapDevices = [{
    device = "/var/lib/swapfile";
    size = 16*1024; # 16 GB
  }];

Bootloader

NixOS supports multiple bootloaders such as GNU GRUB and Systemd/boot.

Systemd-boot is the recommended bootloader. The following example demonstrates how to enable systemd-boot in your configuration:

❄︎ /mnt/etc/nixos/configuration.nix
  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:

❄︎ /mnt/etc/nixos/configuration.nix
  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.
Retrieved from "https://wiki.nixos.org/w/index.php?title=NixOS_Installation_Guide&oldid=24184"