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 `ip`.
158
159You can configure the network, Wi-Fi included, through NetworkManager.
160Using the `nmtui` program, you can do so even in a non-graphical session.
161 If you prefer to configure the network manually, disable NetworkManager with
162`systemctl stop NetworkManager`.
163
164If you would like to continue the installation from a different machine
165you can use activated SSH daemon. You need to copy your ssh key to
166either `/home/nixos/.ssh/authorized_keys` or
167`/root/.ssh/authorized_keys` (Tip: For installers with a modifiable
168filesystem such as the sd-card installer image a key can be manually
169placed by mounting the image on a different machine). Alternatively you
170must set a password for either `root` or `nixos` with `passwd` to be
171able to login.
172
173### Partitioning and formatting {#sec-installation-manual-partitioning}
174[]{#sec-installation-partitioning} <!-- legacy anchor -->
175
176The NixOS installer doesn't do any partitioning or formatting, so you
177need to do that yourself.
178
179The NixOS installer ships with multiple partitioning tools. The examples
180below use `parted`, but also provides `fdisk`, `gdisk`, `cfdisk`, and
181`cgdisk`.
182
183Use the command 'lsblk' to find the name of your 'disk' device.
184
185The recommended partition scheme differs depending if the computer uses
186*Legacy Boot* or *UEFI*.
187
188#### UEFI (GPT) {#sec-installation-manual-partitioning-UEFI}
189[]{#sec-installation-partitioning-UEFI} <!-- legacy anchor -->
190
191Here's an example partition scheme for UEFI, using `/dev/sda` as the
192device.
193
194::: {.note}
195You can safely ignore `parted`'s informational message about needing to
196update /etc/fstab.
197:::
198
1991. Create a *GPT* partition table.
200
201 ```ShellSession
202 # parted /dev/sda -- mklabel gpt
203 ```
204
2052. Add the *root* partition. This will fill the disk except for the end
206 part, where the swap will live, and the space left in front (512MiB)
207 which will be used by the boot partition.
208
209 ```ShellSession
210 # parted /dev/sda -- mkpart root ext4 512MB -8GB
211 ```
212
2133. Next, add a *swap* partition. The size required will vary according
214 to needs, here a 8GB one is created.
215
216 ```ShellSession
217 # parted /dev/sda -- mkpart swap linux-swap -8GB 100%
218 ```
219
220 ::: {.note}
221 The swap partition size rules are no different than for other Linux
222 distributions.
223 :::
224
2254. Finally, the *boot* partition. NixOS by default uses the ESP (EFI
226 system partition) as its */boot* partition. It uses the initially
227 reserved 512MiB at the start of the disk.
228
229 ```ShellSession
230 # parted /dev/sda -- mkpart ESP fat32 1MB 512MB
231 # parted /dev/sda -- set 3 esp on
232 ```
233 ::: {.note}
234 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`.
235 :::
236
237Once complete, you can follow with
238[](#sec-installation-manual-partitioning-formatting).
239
240#### Legacy Boot (MBR) {#sec-installation-manual-partitioning-MBR}
241[]{#sec-installation-partitioning-MBR} <!-- legacy anchor -->
242
243Here's an example partition scheme for Legacy Boot, using `/dev/sda` as
244the device.
245
246::: {.note}
247You can safely ignore `parted`'s informational message about needing to
248update /etc/fstab.
249:::
250
2511. Create a *MBR* partition table.
252
253 ```ShellSession
254 # parted /dev/sda -- mklabel msdos
255 ```
256
2572. Add the *root* partition. This will fill the the disk except for the
258 end part, where the swap will live.
259
260 ```ShellSession
261 # parted /dev/sda -- mkpart primary 1MB -8GB
262 ```
263
2643. Set the root partition's boot flag to on. This allows the disk to be booted from.
265
266 ```ShellSession
267 # parted /dev/sda -- set 1 boot on
268 ```
269
2704. Finally, add a *swap* partition. The size required will vary
271 according to needs, here a 8GB one is created.
272
273 ```ShellSession
274 # parted /dev/sda -- mkpart primary linux-swap -8GB 100%
275 ```
276
277 ::: {.note}
278 The swap partition size rules are no different than for other Linux
279 distributions.
280 :::
281
282Once complete, you can follow with
283[](#sec-installation-manual-partitioning-formatting).
284
285#### Formatting {#sec-installation-manual-partitioning-formatting}
286[]{#sec-installation-partitioning-formatting} <!-- legacy anchor -->
287
288Use the following commands:
289
290- For initialising Ext4 partitions: `mkfs.ext4`. It is recommended
291 that you assign a unique symbolic label to the file system using the
292 option `-L label`, since this makes the file system configuration
293 independent from device changes. For example:
294
295 ```ShellSession
296 # mkfs.ext4 -L nixos /dev/sda1
297 ```
298
299- For creating swap partitions: `mkswap`. Again it's recommended to
300 assign a label to the swap partition: `-L label`. For example:
301
302 ```ShellSession
303 # mkswap -L swap /dev/sda2
304 ```
305
306- **UEFI systems**
307
308 For creating boot partitions: `mkfs.fat`. Again it's recommended
309 to assign a label to the boot partition: `-n label`. For
310 example:
311
312 ```ShellSession
313 # mkfs.fat -F 32 -n boot /dev/sda3
314 ```
315
316- For creating LVM volumes, the LVM commands, e.g., `pvcreate`,
317 `vgcreate`, and `lvcreate`.
318
319- For creating software RAID devices, use `mdadm`.
320
321### Installing {#sec-installation-manual-installing}
322[]{#sec-installation-installing} <!-- legacy anchor -->
323
3241. Mount the target file system on which NixOS should be installed on
325 `/mnt`, e.g.
326
327 ```ShellSession
328 # mount /dev/disk/by-label/nixos /mnt
329 ```
330
3312. **UEFI systems**
332
333 Mount the boot file system on `/mnt/boot`, e.g.
334
335 ```ShellSession
336 # mkdir -p /mnt/boot
337 # mount -o umask=077 /dev/disk/by-label/boot /mnt/boot
338 ```
339
3403. If your machine has a limited amount of memory, you may want to
341 activate swap devices now (`swapon device`).
342 The installer (or rather, the build actions that it
343 may spawn) may need quite a bit of RAM, depending on your
344 configuration.
345
346 ```ShellSession
347 # swapon /dev/sda2
348 ```
349
3504. You now need to create a file `/mnt/etc/nixos/configuration.nix`
351 that specifies the intended configuration of the system. This is
352 because NixOS has a *declarative* configuration model: you create or
353 edit a description of the desired configuration of your system, and
354 then NixOS takes care of making it happen. The syntax of the NixOS
355 configuration file is described in [](#sec-configuration-syntax),
356 while a list of available configuration options appears in
357 [](#ch-options). A minimal example is shown in
358 [Example: NixOS Configuration](#ex-config).
359
360 This command accepts an optional `--flake` option, to also generate a
361 `flake.nix` file, if you want to set up a flake-based configuration.
362
363 The command `nixos-generate-config` can generate an initial
364 configuration file for you:
365
366 ```ShellSession
367 # nixos-generate-config --root /mnt
368 ```
369
370 You should then edit `/mnt/etc/nixos/configuration.nix` to suit your
371 needs:
372
373 ```ShellSession
374 # nano /mnt/etc/nixos/configuration.nix
375 ```
376
377 If you're using the graphical ISO image, other editors may be
378 available (such as `vim`). If you have network access, you can also
379 install other editors -- for instance, you can install Emacs by
380 running `nix-env -f '<nixpkgs>' -iA emacs`.
381
382 BIOS systems
383
384 : You *must* set the option [](#opt-boot.loader.grub.device) to
385 specify on which disk the GRUB boot loader is to be installed.
386 Without it, NixOS cannot boot.
387
388 If there are other operating systems running on the machine before
389 installing NixOS, the [](#opt-boot.loader.grub.useOSProber)
390 option can be set to `true` to automatically add them to the grub
391 menu.
392
393 UEFI systems
394
395 : You must select a boot-loader, either systemd-boot or GRUB. The recommended
396 option is systemd-boot: set the option [](#opt-boot.loader.systemd-boot.enable)
397 to `true`. `nixos-generate-config` should do this automatically
398 for new configurations when booted in UEFI mode.
399
400 You may want to look at the options starting with
401 [`boot.loader.efi`](#opt-boot.loader.efi.canTouchEfiVariables) and
402 [`boot.loader.systemd-boot`](#opt-boot.loader.systemd-boot.enable)
403 as well.
404
405 If you want to use GRUB, set [](#opt-boot.loader.grub.device) to `nodev` and
406 [](#opt-boot.loader.grub.efiSupport) to `true`.
407
408 With systemd-boot, you should not need any special configuration to detect
409 other installed systems. With GRUB, set [](#opt-boot.loader.grub.useOSProber)
410 to `true`, but this will only detect windows partitions, not other Linux
411 distributions. If you dual boot another Linux distribution, use systemd-boot
412 instead.
413
414 If you need to configure networking for your machine the
415 configuration options are described in [](#sec-networking). In
416 particular, while wifi is supported on the installation image, it is
417 not enabled by default in the configuration generated by
418 `nixos-generate-config`.
419
420 Another critical option is `fileSystems`, specifying the file
421 systems that need to be mounted by NixOS. However, you typically
422 don't need to set it yourself, because `nixos-generate-config` sets
423 it automatically in `/mnt/etc/nixos/hardware-configuration.nix` from
424 your currently mounted file systems. (The configuration file
425 `hardware-configuration.nix` is included from `configuration.nix`
426 and will be overwritten by future invocations of
427 `nixos-generate-config`; thus, you generally should not modify it.)
428 Additionally, you may want to look at [Hardware configuration for
429 known-hardware](https://github.com/NixOS/nixos-hardware) at this
430 point or after installation.
431
432 ::: {.note}
433 Depending on your hardware configuration or type of file system, you
434 may need to set the option `boot.initrd.kernelModules` to include
435 the kernel modules that are necessary for mounting the root file
436 system, otherwise the installed system will not be able to boot. (If
437 this happens, boot from the installation media again, mount the
438 target file system on `/mnt`, fix `/mnt/etc/nixos/configuration.nix`
439 and rerun `nixos-install`.) In most cases, `nixos-generate-config`
440 will figure out the required modules.
441 :::
442
4435. Do the installation:
444
445 ```ShellSession
446 # nixos-install
447 ```
448
449 This will install your system based on the configuration you
450 provided. If anything fails due to a configuration problem or any
451 other issue (such as a network outage while downloading binaries
452 from the NixOS binary cache), you can re-run `nixos-install` after
453 fixing your `configuration.nix`.
454
455 If you opted for a flake-based configuration, you will need to pass the
456 `--flake` here as well and specify the name of the configuration as used in
457 the `flake.nix` file. For the default generated flake, this is `nixos`.
458
459 ```ShellSession
460 # nixos-install --flake 'path/to/flake.nix#nixos'
461 ```
462
463 As the last step, `nixos-install` will ask you to set the password
464 for the `root` user, e.g.
465
466 ```plain
467 setting root password...
468 New password: ***
469 Retype new password: ***
470 ```
471
472 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:
473
474 ```ShellSession
475 # nixos-enter --root /mnt -c 'passwd alice'
476 ```
477
478 ::: {.note}
479 For unattended installations, it is possible to use
480 `nixos-install --no-root-passwd` in order to disable the password
481 prompt entirely.
482 :::
483
4846. If everything went well:
485
486 ```ShellSession
487 # reboot
488 ```
489
4907. You should now be able to boot into the installed NixOS. The GRUB
491 boot menu shows a list of *available configurations* (initially just
492 one). Every time you change the NixOS configuration (see [Changing
493 Configuration](#sec-changing-config)), a new item is added to the
494 menu. This allows you to easily roll back to a previous
495 configuration if something goes wrong.
496
497 Use your declared user account to log in.
498 If you didn’t declare one, you should still be able to log in using the `root` user.
499
500 ::: {.note}
501 Some graphical display managers such as SDDM do not allow `root` login by default, so you might need to switch to TTY.
502 Refer to [](#sec-user-management) for details on declaring user accounts.
503 :::
504
505 You may also want to install some software. This will be covered in
506 [](#sec-package-management).
507
508### Installation summary {#sec-installation-manual-summary}
509[]{#sec-installation-summary} <!-- legacy anchor -->
510
511To summarise, [Example: Commands for Installing NixOS on `/dev/sda`](#ex-install-sequence)
512shows a typical sequence of commands for installing NixOS on an empty hard
513drive (here `/dev/sda`). [Example: NixOS Configuration](#ex-config) shows a
514corresponding configuration Nix expression.
515
516::: {#ex-partition-scheme-MBR .example}
517### Example partition schemes for NixOS on `/dev/sda` (MBR)
518```ShellSession
519# parted /dev/sda -- mklabel msdos
520# parted /dev/sda -- mkpart primary 1MB -8GB
521# parted /dev/sda -- mkpart primary linux-swap -8GB 100%
522```
523:::
524
525::: {#ex-partition-scheme-UEFI .example}
526### Example partition schemes for NixOS on `/dev/sda` (UEFI)
527```ShellSession
528# parted /dev/sda -- mklabel gpt
529# parted /dev/sda -- mkpart root ext4 512MB -8GB
530# parted /dev/sda -- mkpart swap linux-swap -8GB 100%
531# parted /dev/sda -- mkpart ESP fat32 1MB 512MB
532# parted /dev/sda -- set 3 esp on
533```
534:::
535
536::: {#ex-install-sequence .example}
537### Commands for Installing NixOS on `/dev/sda`
538
539With a partitioned disk.
540
541```ShellSession
542# mkfs.ext4 -L nixos /dev/sda1
543# mkswap -L swap /dev/sda2
544# swapon /dev/sda2
545# mkfs.fat -F 32 -n boot /dev/sda3 # (for UEFI systems only)
546# mount /dev/disk/by-label/nixos /mnt
547# mkdir -p /mnt/boot # (for UEFI systems only)
548# mount -o umask=077 /dev/disk/by-label/boot /mnt/boot # (for UEFI systems only)
549# nixos-generate-config --root /mnt
550# nano /mnt/etc/nixos/configuration.nix
551# nixos-install
552# reboot
553```
554:::
555
556::: {#ex-config .example}
557### Example: NixOS Configuration
558```ShellSession
559{ config, pkgs, ... }: {
560 imports = [
561 # Include the results of the hardware scan.
562 ./hardware-configuration.nix
563 ];
564
565 boot.loader.grub.device = "/dev/sda"; # (for BIOS systems only)
566 boot.loader.systemd-boot.enable = true; # (for UEFI systems only)
567
568 # Note: setting fileSystems is generally not
569 # necessary, since nixos-generate-config figures them out
570 # automatically in hardware-configuration.nix.
571 #fileSystems."/".device = "/dev/disk/by-label/nixos";
572
573 # Enable the OpenSSH server.
574 services.sshd.enable = true;
575}
576```
577:::
578
579## Additional installation notes {#sec-installation-additional-notes}
580
581```{=include=} sections
582installing-usb.section.md
583installing-pxe.section.md
584installing-kexec.section.md
585installing-virtualbox-guest.section.md
586installing-from-other-distro.section.md
587installing-behind-a-proxy.section.md
588```