pyrox.dev
1# Installing NixOS {#sec-installation}
2
3## Booting from the install medium {#sec-installation-booting}
4
5To begin the installation, you have to boot your computer from the install drive.
6
71. Plug in the install drive. Then turn on or restart your computer.
8
92. Open the boot menu by pressing the appropriate key, which is usually shown
10 on the display on early boot.
11 Select the USB flash drive (the option usually contains the word "USB").
12 If you choose the incorrect drive, your computer will likely continue to
13 boot as normal. In that case restart your computer and pick a
14 different drive.
15
16 ::: {.note}
17 The key to open the boot menu is different across computer brands and even
18 models. It can be [F12]{.keycap}, but also [F1]{.keycap},
19 [F9]{.keycap}, [F10]{.keycap}, [Enter]{.keycap}, [Del]{.keycap},
20 [Esc]{.keycap} or another function key. If you are unsure and don't see
21 it on the early boot screen, you can search online for your computers
22 brand, model followed by "boot from usb".
23 The computer might not even have that feature, so you have to go into the
24 BIOS/UEFI settings to change the boot order. Again, search online for
25 details about your specific computer model.
26
27 For Apple computers with Intel processors press and hold the [⌥]{.keycap}
28 (Option or Alt) key until you see the boot menu. On Apple silicon press
29 and hold the power button.
30 :::
31
32 ::: {.note}
33 If your computer supports both BIOS and UEFI boot, choose the UEFI option.
34 :::
35
36 ::: {.note}
37 If you use a CD for the installation, the computer will probably boot from
38 it automatically. If not, choose the option containing the word "CD" from
39 the boot menu.
40 :::
41
423. Shortly after selecting the appropriate boot drive, you should be
43 presented with a menu with different installer options. Leave the default
44 and wait (or press [Enter]{.keycap} to speed up).
45
464. The graphical images will start their corresponding desktop environment
47 and the graphical installer, which can take some time. The minimal images
48 will boot to a command line. You have to follow the instructions in
49 [](#sec-installation-manual) there.
50
51## Graphical Installation {#sec-installation-graphical}
52
53The graphical installer is recommended for desktop users and will guide you
54through the installation.
55
561. In the "Welcome" screen, you can select the language of the Installer and
57 the installed system.
58
59 ::: {.tip}
60 Leaving the language as "American English" will make it easier to search for
61 error messages in a search engine or to report an issue.
62 :::
63
642. Next you should choose your location to have the timezone set correctly.
65 You can actually click on the map!
66
67 ::: {.note}
68 The installer will use an online service to guess your location based on
69 your public IP address.
70 :::
71
723. Then you can select the keyboard layout. The default keyboard model should
73 work well with most desktop keyboards. If you have a special keyboard or
74 notebook, your model might be in the list. Select the language you are most
75 comfortable typing in.
76
774. On the "Users" screen, you have to type in your display name, login name
78 and password. You can also enable an option to automatically login to the
79 desktop.
80
815. Then you have the option to choose a desktop environment. If you want to
82 create a custom setup with a window manager, you can select "No desktop".
83
84 ::: {.tip}
85 If you don't have a favorite desktop and don't know which one to choose,
86 you can stick to either GNOME or Plasma. They have a quite different
87 design, so you should choose whichever you like better.
88 They are both popular choices and well tested on NixOS.
89 :::
90
916. You have the option to allow unfree software in the next screen.
92
937. The easiest option in the "Partitioning" screen is "Erase disk", which will
94 delete all data from the selected disk and install the system on it.
95 Also select "Swap (with Hibernation)" in the dropdown below it.
96 You have the option to encrypt the whole disk with LUKS.
97
98 ::: {.note}
99 At the top left you see if the Installer was booted with BIOS or UEFI. If
100 you know your system supports UEFI and it shows "BIOS", reboot with the
101 correct option.
102 :::
103
104 ::: {.warning}
105 Make sure you have selected the correct disk at the top and that no
106 valuable data is still on the disk! It will be deleted when
107 formatting the disk.
108 :::
109
1108. Check the choices you made in the "Summary" and click "Install".
111
112 ::: {.note}
113 The installation takes about 15 minutes. The time varies based on the
114 selected desktop environment, internet connection speed and disk write speed.
115 :::
116
1179. When the install is complete, remove the USB flash drive and
118 reboot into your new system!
119
120## Manual Installation {#sec-installation-manual}
121
122NixOS can be installed on BIOS or UEFI systems. The procedure for a UEFI
123installation is broadly the same as for a BIOS installation. The differences
124are mentioned in the following steps.
125
126The NixOS manual is available by running `nixos-help` in the command line
127or from the application menu in the desktop environment.
128
129To have access to the command line on the graphical images, open
130Terminal (GNOME) or Konsole (Plasma) from the application menu.
131
132You are logged-in automatically as `nixos`. The `nixos` user account has
133an empty password so you can use `sudo` without a password:
134
135```ShellSession
136$ sudo -i
137```
138
139You can use `loadkeys` to switch to your preferred keyboard layout.
140(We even provide neo2 via `loadkeys de neo`!)
141
142If the text is too small to be legible, try `setfont ter-v32n` to
143increase the font size.
144
145To install over a serial port connect with `115200n8` (e.g.
146`picocom -b 115200 /dev/ttyUSB0`). When the bootloader lists boot
147entries, select the serial console boot entry.
148
149### Networking in the installer {#sec-installation-manual-networking}
150[]{#sec-installation-booting-networking} <!-- legacy anchor -->
151
152The boot process should have brought up networking (check `ip
153a`). Networking is necessary for the installer, since it will
154download lots of stuff (such as source tarballs or Nixpkgs channel
155binaries). It's best if you have a DHCP server on your network.
156Otherwise configure networking manually using `ifconfig`.
157
158On the graphical installer, you can configure the network, wifi
159included, through NetworkManager. Using the `nmtui` program, you can do
160so even in a non-graphical session. If you prefer to configure the
161network manually, disable NetworkManager with
162`systemctl stop NetworkManager`.
163
164On the minimal installer, NetworkManager is not available, so
165configuration must be performed manually. To configure the wifi, first
166start wpa_supplicant with `sudo systemctl start wpa_supplicant`, then
167run `wpa_cli`. For most home networks, you need to type in the following
168commands:
169
170```plain
171> add_network
1720
173> set_network 0 ssid "myhomenetwork"
174OK
175> set_network 0 psk "mypassword"
176OK
177> set_network 0 key_mgmt WPA-PSK
178OK
179> enable_network 0
180OK
181```
182
183For enterprise networks, for example *eduroam*, instead do:
184
185```plain
186> add_network
1870
188> set_network 0 ssid "eduroam"
189OK
190> set_network 0 identity "myname@example.com"
191OK
192> set_network 0 password "mypassword"
193OK
194> set_network 0 key_mgmt WPA-EAP
195OK
196> enable_network 0
197OK
198```
199
200When successfully connected, you should see a line such as this one
201
202```plain
203<3>CTRL-EVENT-CONNECTED - Connection to 32:85:ab:ef:24:5c completed [id=0 id_str=]
204```
205
206you can now leave `wpa_cli` by typing `quit`.
207
208If you would like to continue the installation from a different machine
209you can use activated SSH daemon. You need to copy your ssh key to
210either `/home/nixos/.ssh/authorized_keys` or
211`/root/.ssh/authorized_keys` (Tip: For installers with a modifiable
212filesystem such as the sd-card installer image a key can be manually
213placed by mounting the image on a different machine). Alternatively you
214must set a password for either `root` or `nixos` with `passwd` to be
215able to login.
216
217### Partitioning and formatting {#sec-installation-manual-partitioning}
218[]{#sec-installation-partitioning} <!-- legacy anchor -->
219
220The NixOS installer doesn't do any partitioning or formatting, so you
221need to do that yourself.
222
223The NixOS installer ships with multiple partitioning tools. The examples
224below use `parted`, but also provides `fdisk`, `gdisk`, `cfdisk`, and
225`cgdisk`.
226
227The recommended partition scheme differs depending if the computer uses
228*Legacy Boot* or *UEFI*.
229
230#### UEFI (GPT) {#sec-installation-manual-partitioning-UEFI}
231[]{#sec-installation-partitioning-UEFI} <!-- legacy anchor -->
232
233Here's an example partition scheme for UEFI, using `/dev/sda` as the
234device.
235
236::: {.note}
237You can safely ignore `parted`'s informational message about needing to
238update /etc/fstab.
239:::
240
2411. Create a *GPT* partition table.
242
243 ```ShellSession
244 # parted /dev/sda -- mklabel gpt
245 ```
246
2472. Add the *root* partition. This will fill the disk except for the end
248 part, where the swap will live, and the space left in front (512MiB)
249 which will be used by the boot partition.
250
251 ```ShellSession
252 # parted /dev/sda -- mkpart root ext4 512MB -8GB
253 ```
254
2553. Next, add a *swap* partition. The size required will vary according
256 to needs, here a 8GB one is created.
257
258 ```ShellSession
259 # parted /dev/sda -- mkpart swap linux-swap -8GB 100%
260 ```
261
262 ::: {.note}
263 The swap partition size rules are no different than for other Linux
264 distributions.
265 :::
266
2674. Finally, the *boot* partition. NixOS by default uses the ESP (EFI
268 system partition) as its */boot* partition. It uses the initially
269 reserved 512MiB at the start of the disk.
270
271 ```ShellSession
272 # parted /dev/sda -- mkpart ESP fat32 1MB 512MB
273 # parted /dev/sda -- set 3 esp on
274 ```
275 ::: {.note}
276 In case you decided to not create a swap partition, replace `3` by `2`. To be sure of the id number of ESP, run `parted --list`.
277 :::
278
279Once complete, you can follow with
280[](#sec-installation-manual-partitioning-formatting).
281
282#### Legacy Boot (MBR) {#sec-installation-manual-partitioning-MBR}
283[]{#sec-installation-partitioning-MBR} <!-- legacy anchor -->
284
285Here's an example partition scheme for Legacy Boot, using `/dev/sda` as
286the device.
287
288::: {.note}
289You can safely ignore `parted`'s informational message about needing to
290update /etc/fstab.
291:::
292
2931. Create a *MBR* partition table.
294
295 ```ShellSession
296 # parted /dev/sda -- mklabel msdos
297 ```
298
2992. Add the *root* partition. This will fill the the disk except for the
300 end part, where the swap will live.
301
302 ```ShellSession
303 # parted /dev/sda -- mkpart primary 1MB -8GB
304 ```
305
3063. Set the root partition's boot flag to on. This allows the disk to be booted from.
307
308 ```ShellSession
309 # parted /dev/sda -- set 1 boot on
310 ```
311
3124. Finally, add a *swap* partition. The size required will vary
313 according to needs, here a 8GB one is created.
314
315 ```ShellSession
316 # parted /dev/sda -- mkpart primary linux-swap -8GB 100%
317 ```
318
319 ::: {.note}
320 The swap partition size rules are no different than for other Linux
321 distributions.
322 :::
323
324Once complete, you can follow with
325[](#sec-installation-manual-partitioning-formatting).
326
327#### Formatting {#sec-installation-manual-partitioning-formatting}
328[]{#sec-installation-partitioning-formatting} <!-- legacy anchor -->
329
330Use the following commands:
331
332- For initialising Ext4 partitions: `mkfs.ext4`. It is recommended
333 that you assign a unique symbolic label to the file system using the
334 option `-L label`, since this makes the file system configuration
335 independent from device changes. For example:
336
337 ```ShellSession
338 # mkfs.ext4 -L nixos /dev/sda1
339 ```
340
341- For creating swap partitions: `mkswap`. Again it's recommended to
342 assign a label to the swap partition: `-L label`. For example:
343
344 ```ShellSession
345 # mkswap -L swap /dev/sda2
346 ```
347
348- **UEFI systems**
349
350 For creating boot partitions: `mkfs.fat`. Again it's recommended
351 to assign a label to the boot partition: `-n label`. For
352 example:
353
354 ```ShellSession
355 # mkfs.fat -F 32 -n boot /dev/sda3
356 ```
357
358- For creating LVM volumes, the LVM commands, e.g., `pvcreate`,
359 `vgcreate`, and `lvcreate`.
360
361- For creating software RAID devices, use `mdadm`.
362
363### Installing {#sec-installation-manual-installing}
364[]{#sec-installation-installing} <!-- legacy anchor -->
365
3661. Mount the target file system on which NixOS should be installed on
367 `/mnt`, e.g.
368
369 ```ShellSession
370 # mount /dev/disk/by-label/nixos /mnt
371 ```
372
3732. **UEFI systems**
374
375 Mount the boot file system on `/mnt/boot`, e.g.
376
377 ```ShellSession
378 # mkdir -p /mnt/boot
379 # mount -o umask=077 /dev/disk/by-label/boot /mnt/boot
380 ```
381
3823. If your machine has a limited amount of memory, you may want to
383 activate swap devices now (`swapon device`).
384 The installer (or rather, the build actions that it
385 may spawn) may need quite a bit of RAM, depending on your
386 configuration.
387
388 ```ShellSession
389 # swapon /dev/sda2
390 ```
391
3924. You now need to create a file `/mnt/etc/nixos/configuration.nix`
393 that specifies the intended configuration of the system. This is
394 because NixOS has a *declarative* configuration model: you create or
395 edit a description of the desired configuration of your system, and
396 then NixOS takes care of making it happen. The syntax of the NixOS
397 configuration file is described in [](#sec-configuration-syntax),
398 while a list of available configuration options appears in
399 [](#ch-options). A minimal example is shown in
400 [Example: NixOS Configuration](#ex-config).
401
402 The command `nixos-generate-config` can generate an initial
403 configuration file for you:
404
405 ```ShellSession
406 # nixos-generate-config --root /mnt
407 ```
408
409 You should then edit `/mnt/etc/nixos/configuration.nix` to suit your
410 needs:
411
412 ```ShellSession
413 # nano /mnt/etc/nixos/configuration.nix
414 ```
415
416 If you're using the graphical ISO image, other editors may be
417 available (such as `vim`). If you have network access, you can also
418 install other editors -- for instance, you can install Emacs by
419 running `nix-env -f '<nixpkgs>' -iA emacs`.
420
421 BIOS systems
422
423 : You *must* set the option [](#opt-boot.loader.grub.device) to
424 specify on which disk the GRUB boot loader is to be installed.
425 Without it, NixOS cannot boot.
426
427 If there are other operating systems running on the machine before
428 installing NixOS, the [](#opt-boot.loader.grub.useOSProber)
429 option can be set to `true` to automatically add them to the grub
430 menu.
431
432 UEFI systems
433
434 : You must select a boot-loader, either systemd-boot or GRUB. The recommended
435 option is systemd-boot: set the option [](#opt-boot.loader.systemd-boot.enable)
436 to `true`. `nixos-generate-config` should do this automatically
437 for new configurations when booted in UEFI mode.
438
439 You may want to look at the options starting with
440 [`boot.loader.efi`](#opt-boot.loader.efi.canTouchEfiVariables) and
441 [`boot.loader.systemd-boot`](#opt-boot.loader.systemd-boot.enable)
442 as well.
443
444 If you want to use GRUB, set [](#opt-boot.loader.grub.device) to `nodev` and
445 [](#opt-boot.loader.grub.efiSupport) to `true`.
446
447 With systemd-boot, you should not need any special configuration to detect
448 other installed systems. With GRUB, set [](#opt-boot.loader.grub.useOSProber)
449 to `true`, but this will only detect windows partitions, not other Linux
450 distributions. If you dual boot another Linux distribution, use systemd-boot
451 instead.
452
453 If you need to configure networking for your machine the
454 configuration options are described in [](#sec-networking). In
455 particular, while wifi is supported on the installation image, it is
456 not enabled by default in the configuration generated by
457 `nixos-generate-config`.
458
459 Another critical option is `fileSystems`, specifying the file
460 systems that need to be mounted by NixOS. However, you typically
461 don't need to set it yourself, because `nixos-generate-config` sets
462 it automatically in `/mnt/etc/nixos/hardware-configuration.nix` from
463 your currently mounted file systems. (The configuration file
464 `hardware-configuration.nix` is included from `configuration.nix`
465 and will be overwritten by future invocations of
466 `nixos-generate-config`; thus, you generally should not modify it.)
467 Additionally, you may want to look at [Hardware configuration for
468 known-hardware](https://github.com/NixOS/nixos-hardware) at this
469 point or after installation.
470
471 ::: {.note}
472 Depending on your hardware configuration or type of file system, you
473 may need to set the option `boot.initrd.kernelModules` to include
474 the kernel modules that are necessary for mounting the root file
475 system, otherwise the installed system will not be able to boot. (If
476 this happens, boot from the installation media again, mount the
477 target file system on `/mnt`, fix `/mnt/etc/nixos/configuration.nix`
478 and rerun `nixos-install`.) In most cases, `nixos-generate-config`
479 will figure out the required modules.
480 :::
481
4825. Do the installation:
483
484 ```ShellSession
485 # nixos-install
486 ```
487
488 This will install your system based on the configuration you
489 provided. If anything fails due to a configuration problem or any
490 other issue (such as a network outage while downloading binaries
491 from the NixOS binary cache), you can re-run `nixos-install` after
492 fixing your `configuration.nix`.
493
494 As the last step, `nixos-install` will ask you to set the password
495 for the `root` user, e.g.
496
497 ```plain
498 setting root password...
499 New password: ***
500 Retype new password: ***
501 ```
502
503 ::: {.note}
504 For unattended installations, it is possible to use
505 `nixos-install --no-root-passwd` in order to disable the password
506 prompt entirely.
507 :::
508
5096. If everything went well:
510
511 ```ShellSession
512 # reboot
513 ```
514
5157. You should now be able to boot into the installed NixOS. The GRUB
516 boot menu shows a list of *available configurations* (initially just
517 one). Every time you change the NixOS configuration (see [Changing
518 Configuration](#sec-changing-config)), a new item is added to the
519 menu. This allows you to easily roll back to a previous
520 configuration if something goes wrong.
521
522 You should log in and change the `root` password with `passwd`.
523
524 You'll probably want to create some user accounts as well, which can
525 be done with `useradd`:
526
527 ```ShellSession
528 $ useradd -c 'Eelco Dolstra' -m eelco
529 $ passwd eelco
530 ```
531
532 You may also want to install some software. This will be covered in
533 [](#sec-package-management).
534
535### Installation summary {#sec-installation-manual-summary}
536[]{#sec-installation-summary} <!-- legacy anchor -->
537
538To summarise, [Example: Commands for Installing NixOS on `/dev/sda`](#ex-install-sequence)
539shows a typical sequence of commands for installing NixOS on an empty hard
540drive (here `/dev/sda`). [Example: NixOS Configuration](#ex-config) shows a
541corresponding configuration Nix expression.
542
543::: {#ex-partition-scheme-MBR .example}
544### Example partition schemes for NixOS on `/dev/sda` (MBR)
545```ShellSession
546# parted /dev/sda -- mklabel msdos
547# parted /dev/sda -- mkpart primary 1MB -8GB
548# parted /dev/sda -- mkpart primary linux-swap -8GB 100%
549```
550:::
551
552::: {#ex-partition-scheme-UEFI .example}
553### Example partition schemes for NixOS on `/dev/sda` (UEFI)
554```ShellSession
555# parted /dev/sda -- mklabel gpt
556# parted /dev/sda -- mkpart root ext4 512MB -8GB
557# parted /dev/sda -- mkpart swap linux-swap -8GB 100%
558# parted /dev/sda -- mkpart ESP fat32 1MB 512MB
559# parted /dev/sda -- set 3 esp on
560```
561:::
562
563::: {#ex-install-sequence .example}
564### Commands for Installing NixOS on `/dev/sda`
565
566With a partitioned disk.
567
568```ShellSession
569# mkfs.ext4 -L nixos /dev/sda1
570# mkswap -L swap /dev/sda2
571# swapon /dev/sda2
572# mkfs.fat -F 32 -n boot /dev/sda3 # (for UEFI systems only)
573# mount /dev/disk/by-label/nixos /mnt
574# mkdir -p /mnt/boot # (for UEFI systems only)
575# mount -o umask=077 /dev/disk/by-label/boot /mnt/boot # (for UEFI systems only)
576# nixos-generate-config --root /mnt
577# nano /mnt/etc/nixos/configuration.nix
578# nixos-install
579# reboot
580```
581:::
582
583::: {#ex-config .example}
584### Example: NixOS Configuration
585```ShellSession
586{ config, pkgs, ... }: {
587 imports = [
588 # Include the results of the hardware scan.
589 ./hardware-configuration.nix
590 ];
591
592 boot.loader.grub.device = "/dev/sda"; # (for BIOS systems only)
593 boot.loader.systemd-boot.enable = true; # (for UEFI systems only)
594
595 # Note: setting fileSystems is generally not
596 # necessary, since nixos-generate-config figures them out
597 # automatically in hardware-configuration.nix.
598 #fileSystems."/".device = "/dev/disk/by-label/nixos";
599
600 # Enable the OpenSSH server.
601 services.sshd.enable = true;
602}
603```
604:::
605
606## Additional installation notes {#sec-installation-additional-notes}
607
608```{=include=} sections
609installing-usb.section.md
610installing-pxe.section.md
611installing-kexec.section.md
612installing-virtualbox-guest.section.md
613installing-from-other-distro.section.md
614installing-behind-a-proxy.section.md
615```