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