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 primary 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 primary 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
276Once complete, you can follow with
277[](#sec-installation-manual-partitioning-formatting).
278
279#### Legacy Boot (MBR) {#sec-installation-manual-partitioning-MBR}
280[]{#sec-installation-partitioning-MBR} <!-- legacy anchor -->
281
282Here's an example partition scheme for Legacy Boot, using `/dev/sda` as
283the device.
284
285::: {.note}
286You can safely ignore `parted`'s informational message about needing to
287update /etc/fstab.
288:::
289
2901. Create a *MBR* partition table.
291
292 ```ShellSession
293 # parted /dev/sda -- mklabel msdos
294 ```
295
2962. Add the *root* partition. This will fill the the disk except for the
297 end part, where the swap will live.
298
299 ```ShellSession
300 # parted /dev/sda -- mkpart primary 1MB -8GB
301 ```
302
3033. Set the root partition's boot flag to on. This allows the disk to be booted from.
304
305 ```ShellSession
306 # parted /dev/sda -- set 1 boot on
307 ```
308
3094. Finally, add a *swap* partition. The size required will vary
310 according to needs, here a 8GB one is created.
311
312 ```ShellSession
313 # parted /dev/sda -- mkpart primary linux-swap -8GB 100%
314 ```
315
316 ::: {.note}
317 The swap partition size rules are no different than for other Linux
318 distributions.
319 :::
320
321Once complete, you can follow with
322[](#sec-installation-manual-partitioning-formatting).
323
324#### Formatting {#sec-installation-manual-partitioning-formatting}
325[]{#sec-installation-partitioning-formatting} <!-- legacy anchor -->
326
327Use the following commands:
328
329- For initialising Ext4 partitions: `mkfs.ext4`. It is recommended
330 that you assign a unique symbolic label to the file system using the
331 option `-L label`, since this makes the file system configuration
332 independent from device changes. For example:
333
334 ```ShellSession
335 # mkfs.ext4 -L nixos /dev/sda1
336 ```
337
338- For creating swap partitions: `mkswap`. Again it's recommended to
339 assign a label to the swap partition: `-L label`. For example:
340
341 ```ShellSession
342 # mkswap -L swap /dev/sda2
343 ```
344
345- **UEFI systems**
346
347 For creating boot partitions: `mkfs.fat`. Again it's recommended
348 to assign a label to the boot partition: `-n label`. For
349 example:
350
351 ```ShellSession
352 # mkfs.fat -F 32 -n boot /dev/sda3
353 ```
354
355- For creating LVM volumes, the LVM commands, e.g., `pvcreate`,
356 `vgcreate`, and `lvcreate`.
357
358- For creating software RAID devices, use `mdadm`.
359
360### Installing {#sec-installation-manual-installing}
361[]{#sec-installation-installing} <!-- legacy anchor -->
362
3631. Mount the target file system on which NixOS should be installed on
364 `/mnt`, e.g.
365
366 ```ShellSession
367 # mount /dev/disk/by-label/nixos /mnt
368 ```
369
3702. **UEFI systems**
371
372 Mount the boot file system on `/mnt/boot`, e.g.
373
374 ```ShellSession
375 # mkdir -p /mnt/boot
376 # mount /dev/disk/by-label/boot /mnt/boot
377 ```
378
3793. If your machine has a limited amount of memory, you may want to
380 activate swap devices now (`swapon device`).
381 The installer (or rather, the build actions that it
382 may spawn) may need quite a bit of RAM, depending on your
383 configuration.
384
385 ```ShellSession
386 # swapon /dev/sda2
387 ```
388
3894. You now need to create a file `/mnt/etc/nixos/configuration.nix`
390 that specifies the intended configuration of the system. This is
391 because NixOS has a *declarative* configuration model: you create or
392 edit a description of the desired configuration of your system, and
393 then NixOS takes care of making it happen. The syntax of the NixOS
394 configuration file is described in [](#sec-configuration-syntax),
395 while a list of available configuration options appears in
396 [](#ch-options). A minimal example is shown in
397 [Example: NixOS Configuration](#ex-config).
398
399 The command `nixos-generate-config` can generate an initial
400 configuration file for you:
401
402 ```ShellSession
403 # nixos-generate-config --root /mnt
404 ```
405
406 You should then edit `/mnt/etc/nixos/configuration.nix` to suit your
407 needs:
408
409 ```ShellSession
410 # nano /mnt/etc/nixos/configuration.nix
411 ```
412
413 If you're using the graphical ISO image, other editors may be
414 available (such as `vim`). If you have network access, you can also
415 install other editors -- for instance, you can install Emacs by
416 running `nix-env -f '<nixpkgs>' -iA emacs`.
417
418 BIOS systems
419
420 : You *must* set the option [](#opt-boot.loader.grub.device) to
421 specify on which disk the GRUB boot loader is to be installed.
422 Without it, NixOS cannot boot.
423
424 If there are other operating systems running on the machine before
425 installing NixOS, the [](#opt-boot.loader.grub.useOSProber)
426 option can be set to `true` to automatically add them to the grub
427 menu.
428
429 UEFI systems
430
431 : You must select a boot-loader, either systemd-boot or GRUB. The recommended
432 option is systemd-boot: set the option [](#opt-boot.loader.systemd-boot.enable)
433 to `true`. `nixos-generate-config` should do this automatically
434 for new configurations when booted in UEFI mode.
435
436 You may want to look at the options starting with
437 [`boot.loader.efi`](#opt-boot.loader.efi.canTouchEfiVariables) and
438 [`boot.loader.systemd-boot`](#opt-boot.loader.systemd-boot.enable)
439 as well.
440
441 If you want to use GRUB, set [](#opt-boot.loader.grub.device) to `nodev` and
442 [](#opt-boot.loader.grub.efiSupport) to `true`.
443
444 With systemd-boot, you should not need any special configuration to detect
445 other installed systems. With GRUB, set [](#opt-boot.loader.grub.useOSProber)
446 to `true`, but this will only detect windows partitions, not other Linux
447 distributions. If you dual boot another Linux distribution, use systemd-boot
448 instead.
449
450 If you need to configure networking for your machine the
451 configuration options are described in [](#sec-networking). In
452 particular, while wifi is supported on the installation image, it is
453 not enabled by default in the configuration generated by
454 `nixos-generate-config`.
455
456 Another critical option is `fileSystems`, specifying the file
457 systems that need to be mounted by NixOS. However, you typically
458 don't need to set it yourself, because `nixos-generate-config` sets
459 it automatically in `/mnt/etc/nixos/hardware-configuration.nix` from
460 your currently mounted file systems. (The configuration file
461 `hardware-configuration.nix` is included from `configuration.nix`
462 and will be overwritten by future invocations of
463 `nixos-generate-config`; thus, you generally should not modify it.)
464 Additionally, you may want to look at [Hardware configuration for
465 known-hardware](https://github.com/NixOS/nixos-hardware) at this
466 point or after installation.
467
468 ::: {.note}
469 Depending on your hardware configuration or type of file system, you
470 may need to set the option `boot.initrd.kernelModules` to include
471 the kernel modules that are necessary for mounting the root file
472 system, otherwise the installed system will not be able to boot. (If
473 this happens, boot from the installation media again, mount the
474 target file system on `/mnt`, fix `/mnt/etc/nixos/configuration.nix`
475 and rerun `nixos-install`.) In most cases, `nixos-generate-config`
476 will figure out the required modules.
477 :::
478
4795. Do the installation:
480
481 ```ShellSession
482 # nixos-install
483 ```
484
485 This will install your system based on the configuration you
486 provided. If anything fails due to a configuration problem or any
487 other issue (such as a network outage while downloading binaries
488 from the NixOS binary cache), you can re-run `nixos-install` after
489 fixing your `configuration.nix`.
490
491 As the last step, `nixos-install` will ask you to set the password
492 for the `root` user, e.g.
493
494 ```plain
495 setting root password...
496 New password: ***
497 Retype new password: ***
498 ```
499
500 ::: {.note}
501 For unattended installations, it is possible to use
502 `nixos-install --no-root-passwd` in order to disable the password
503 prompt entirely.
504 :::
505
5066. If everything went well:
507
508 ```ShellSession
509 # reboot
510 ```
511
5127. You should now be able to boot into the installed NixOS. The GRUB
513 boot menu shows a list of *available configurations* (initially just
514 one). Every time you change the NixOS configuration (see [Changing
515 Configuration](#sec-changing-config)), a new item is added to the
516 menu. This allows you to easily roll back to a previous
517 configuration if something goes wrong.
518
519 You should log in and change the `root` password with `passwd`.
520
521 You'll probably want to create some user accounts as well, which can
522 be done with `useradd`:
523
524 ```ShellSession
525 $ useradd -c 'Eelco Dolstra' -m eelco
526 $ passwd eelco
527 ```
528
529 You may also want to install some software. This will be covered in
530 [](#sec-package-management).
531
532### Installation summary {#sec-installation-manual-summary}
533[]{#sec-installation-summary} <!-- legacy anchor -->
534
535To summarise, [Example: Commands for Installing NixOS on `/dev/sda`](#ex-install-sequence)
536shows a typical sequence of commands for installing NixOS on an empty hard
537drive (here `/dev/sda`). [Example: NixOS Configuration](#ex-config) shows a
538corresponding configuration Nix expression.
539
540::: {#ex-partition-scheme-MBR .example}
541### Example partition schemes for NixOS on `/dev/sda` (MBR)
542```ShellSession
543# parted /dev/sda -- mklabel msdos
544# parted /dev/sda -- mkpart primary 1MB -8GB
545# parted /dev/sda -- mkpart primary linux-swap -8GB 100%
546```
547:::
548
549::: {#ex-partition-scheme-UEFI .example}
550### Example partition schemes for NixOS on `/dev/sda` (UEFI)
551```ShellSession
552# parted /dev/sda -- mklabel gpt
553# parted /dev/sda -- mkpart primary 512MB -8GB
554# parted /dev/sda -- mkpart primary linux-swap -8GB 100%
555# parted /dev/sda -- mkpart ESP fat32 1MB 512MB
556# parted /dev/sda -- set 3 esp on
557```
558:::
559
560::: {#ex-install-sequence .example}
561### Commands for Installing NixOS on `/dev/sda`
562
563With a partitioned disk.
564
565```ShellSession
566# mkfs.ext4 -L nixos /dev/sda1
567# mkswap -L swap /dev/sda2
568# swapon /dev/sda2
569# mkfs.fat -F 32 -n boot /dev/sda3 # (for UEFI systems only)
570# mount /dev/disk/by-label/nixos /mnt
571# mkdir -p /mnt/boot # (for UEFI systems only)
572# mount /dev/disk/by-label/boot /mnt/boot # (for UEFI systems only)
573# nixos-generate-config --root /mnt
574# nano /mnt/etc/nixos/configuration.nix
575# nixos-install
576# reboot
577```
578:::
579
580::: {#ex-config .example}
581### Example: NixOS Configuration
582```ShellSession
583{ config, pkgs, ... }: {
584 imports = [
585 # Include the results of the hardware scan.
586 ./hardware-configuration.nix
587 ];
588
589 boot.loader.grub.device = "/dev/sda"; # (for BIOS systems only)
590 boot.loader.systemd-boot.enable = true; # (for UEFI systems only)
591
592 # Note: setting fileSystems is generally not
593 # necessary, since nixos-generate-config figures them out
594 # automatically in hardware-configuration.nix.
595 #fileSystems."/".device = "/dev/disk/by-label/nixos";
596
597 # Enable the OpenSSH server.
598 services.sshd.enable = true;
599}
600```
601:::
602
603## Additional installation notes {#sec-installation-additional-notes}
604
605```{=include=} sections
606installing-usb.section.md
607installing-pxe.section.md
608installing-kexec.section.md
609installing-virtualbox-guest.section.md
610installing-from-other-distro.section.md
611installing-behind-a-proxy.section.md
612```