diff --git a/nixos/doc/manual/from_md/installation/installing-usb.section.xml b/nixos/doc/manual/from_md/installation/installing-usb.section.xml
index df266eb16800..9d12ac45aac2 100644
--- a/nixos/doc/manual/from_md/installation/installing-usb.section.xml
+++ b/nixos/doc/manual/from_md/installation/installing-usb.section.xml
@@ -1,35 +1,135 @@
- Booting from a USB Drive
+ Booting from a USB flash drive
- For systems without CD drive, the NixOS live CD can be booted from a
- USB stick. You can use the dd utility to write
- the image: dd if=path-to-image of=/dev/sdX. Be
- careful about specifying the correct drive; you can use the
- lsblk command to get a list of block devices.
+ The image has to be written verbatim to the USB flash drive for it
+ to be bootable on UEFI and BIOS systems. Here are the recommended
+ tools to do that.
-
- On macOS
+
+ Creating bootable USB flash drive with a graphical
+ tool
+
+ Etcher is a popular and user-friendly tool. It works on Linux,
+ Windows and macOS.
+
+
+ Download it from
+ balena.io,
+ start the program, select the downloaded NixOS ISO, then select
+ the USB flash drive and flash it.
+
+
+
+ Etcher reports errors and usage statistics by default, which can
+ be disabled in the settings.
+
+
+
+ An alternative is
+ USBImager,
+ which is very simple and does not connect to the internet.
+ Download the version with write-only (wo) interface for your
+ system. Start the program, select the image, select the USB flash
+ drive and click Write.
+
+
+
+ Creating bootable USB flash drive from a Terminal on
+ Linux
+
+
+
+ Plug in the USB flash drive.
+
+
+
+
+ Find the corresponding device with lsblk.
+ You can distinguish them by their size.
+
+
+
+
+ Make sure all partitions on the device are properly unmounted.
+ Replace sdX with your device (e.g.
+ sdb).
+
+
+
-$ diskutil list
-[..]
-/dev/diskN (external, physical):
- #: TYPE NAME SIZE IDENTIFIER
-[..]
-$ diskutil unmountDisk diskN
-Unmount of all volumes on diskN was successful
-$ sudo dd if=nix.iso of=/dev/rdiskN bs=1M
+sudo umount /dev/sdX*
+
+
+
+
+ Then use the dd utility to write the image
+ to the USB flash drive.
+
+
+
+
+sudo dd if=<path-to-image> of=/dev/sdX bs=4M conv=fsync
+
+
+
+ Creating bootable USB flash drive from a Terminal on
+ macOS
+
+
+
+ Plug in the USB flash drive.
+
+
+
+
+ Find the corresponding device with
+ diskutil list. You can distinguish them by
+ their size.
+
+
+
+
+ Make sure all partitions on the device are properly unmounted.
+ Replace diskX with your device (e.g.
+ disk1).
+
+
+
+
+diskutil unmountDisk diskX
+
+
+
+
+ Then use the dd utility to write the image
+ to the USB flash drive.
+
+
+
+
+sudo dd if=<path-to-image> of=/dev/rdiskX bs=4m
- Using the 'raw' rdiskN device instead of
- diskN completes in minutes instead of hours.
After dd completes, a GUI dialog "The disk
you inserted was not readable by this computer" will pop up,
which can be ignored.
-
-
- The dd utility will write the image verbatim to
- the drive, making it the recommended option for both UEFI and
- non-UEFI installations.
-
+
+
+ Using the 'raw' rdiskX device instead of
+ diskX with dd completes in minutes instead of
+ hours.
+
+
+
+
+
+ Eject the disk when it is finished.
+
+
+
+
+diskutil eject /dev/diskX
+
+
diff --git a/nixos/doc/manual/from_md/installation/installing.chapter.xml b/nixos/doc/manual/from_md/installation/installing.chapter.xml
index e0ff368b800c..02a0f14b984a 100644
--- a/nixos/doc/manual/from_md/installation/installing.chapter.xml
+++ b/nixos/doc/manual/from_md/installation/installing.chapter.xml
@@ -1,26 +1,212 @@
Installing NixOS
- Booting the system
+ Booting from the install medium
+
+ To begin the installation, you have to boot your computer from the
+ install drive.
+
+
+
+
+ Plug in the install drive. Then turn on or restart your
+ computer.
+
+
+
+
+ Open the boot menu by pressing the appropriate key, which is
+ usually shown on the display on early boot. Select the USB
+ flash drive (the option usually contains the word
+ USB). If you choose the incorrect drive, your
+ computer will likely continue to boot as normal. In that case
+ restart your computer and pick a different drive.
+
+
+
+ The key to open the boot menu is different across computer
+ brands and even models. It can be F12, but
+ also F1, F9,
+ F10, Enter,
+ Del, Esc or another
+ function key. If you are unsure and don’t see it on the
+ early boot screen, you can search online for your computers
+ brand, model followed by boot from usb. The
+ computer might not even have that feature, so you have to go
+ into the BIOS/UEFI settings to change the boot order. Again,
+ search online for details about your specific computer
+ model.
+
+
+ For Apple computers with Intel processors press and hold the
+ ⌥ (Option or Alt) key until you see the
+ boot menu. On Apple silicon press and hold the power button.
+
+
+
+
+ If your computer supports both BIOS and UEFI boot, choose
+ the UEFI option.
+
+
+
+
+ If you use a CD for the installation, the computer will
+ probably boot from it automatically. If not, choose the
+ option containing the word CD from the boot
+ menu.
+
+
+
+
+
+ Shortly after selecting the appropriate boot drive, you should
+ be presented with a menu with different installer options.
+ Leave the default and wait (or press Enter to
+ speed up).
+
+
+
+
+ The graphical images will start their corresponding desktop
+ environment and the graphical installer, which can take some
+ time. The minimal images will boot to a command line. You have
+ to follow the instructions in
+ there.
+
+
+
+
+
+ Graphical Installation
+
+ The graphical installer is recommended for desktop users and will
+ guide you through the installation.
+
+
+
+
+ In the Welcome screen, you can select the
+ language of the Installer and the installed system.
+
+
+
+ Leaving the language as American English will
+ make it easier to search for error messages in a search
+ engine or to report an issue.
+
+
+
+
+
+ Next you should choose your location to have the timezone set
+ correctly. You can actually click on the map!
+
+
+
+ The installer will use an online service to guess your
+ location based on your public IP address.
+
+
+
+
+
+ Then you can select the keyboard layout. The default keyboard
+ model should work well with most desktop keyboards. If you
+ have a special keyboard or notebook, your model might be in
+ the list. Select the language you are most comfortable typing
+ in.
+
+
+
+
+ On the Users screen, you have to type in your
+ display name, login name and password. You can also enable an
+ option to automatically login to the desktop.
+
+
+
+
+ Then you have the option to choose a desktop environment. If
+ you want to create a custom setup with a window manager, you
+ can select No desktop.
+
+
+
+ If you don’t have a favorite desktop and don’t know which
+ one to choose, you can stick to either GNOME or Plasma. They
+ have a quite different design, so you should choose
+ whichever you like better. They are both popular choices and
+ well tested on NixOS.
+
+
+
+
+
+ You have the option to allow unfree software in the next
+ screen.
+
+
+
+
+ The easiest option in the Partitioning screen
+ is Erase disk, which will delete all data from
+ the selected disk and install the system on it. Also select
+ Swap (with Hibernation) in the dropdown below
+ it. You have the option to encrypt the whole disk with LUKS.
+
+
+
+ At the top left you see if the Installer was booted with
+ BIOS or UEFI. If you know your system supports UEFI and it
+ shows BIOS, reboot with the correct option.
+
+
+
+
+ Make sure you have selected the correct disk at the top and
+ that no valuable data is still on the disk! It will be
+ deleted when formatting the disk.
+
+
+
+
+
+ Check the choices you made in the Summary and
+ click Install.
+
+
+
+ The installation takes about 15 minutes. The time varies
+ based on the selected desktop environment, internet
+ connection speed and disk write speed.
+
+
+
+
+
+ When the install is complete, remove the USB flash drive and
+ reboot into your new system!
+
+
+
+
+
+ Manual Installation
NixOS can be installed on BIOS or UEFI systems. The procedure for
- a UEFI installation is by and large the same as a BIOS
- installation. The differences are mentioned in the steps that
- follow.
-
-
- The installation media can be burned to a CD, or now more
- commonly, burned to a USB drive (see
- ).
-
-
- The installation media contains a basic NixOS installation. When
- it’s finished booting, it should have detected most of your
- hardware.
+ a UEFI installation is broadly the same as for a BIOS
+ installation. The differences are mentioned in the following
+ steps.
The NixOS manual is available by running
- nixos-help.
+ nixos-help in the command line or from the
+ application menu in the desktop environment.
+
+
+ To have access to the command line on the graphical images, open
+ Terminal (GNOME) or Konsole (Plasma) from the application menu.
You are logged-in automatically as nixos. The
@@ -31,11 +217,8 @@
$ sudo -i
- If you downloaded the graphical ISO image, you can run
- systemctl start display-manager to start the
- desktop environment. If you want to continue on the terminal, you
- can use loadkeys to switch to your preferred
- keyboard layout. (We even provide neo2 via
+ You can use loadkeys to switch to your
+ preferred keyboard layout. (We even provide neo2 via
loadkeys de neo!)
@@ -49,8 +232,12 @@ $ sudo -i
bootloader lists boot entries, select the serial console boot
entry.
-
+ Networking in the installer
+
+
+
+
The boot process should have brought up networking (check
ip a). Networking is necessary for the
@@ -130,179 +317,239 @@ OK
able to login.
-
-
- Partitioning and formatting
-
- The NixOS installer doesn’t do any partitioning or formatting, so
- you need to do that yourself.
-
-
- The NixOS installer ships with multiple partitioning tools. The
- examples below use parted, but also provides
- fdisk, gdisk,
- cfdisk, and cgdisk.
-
-
- The recommended partition scheme differs depending if the computer
- uses Legacy Boot or
- UEFI.
-
-
- UEFI (GPT)
+
+ Partitioning and formatting
- Here's an example partition scheme for UEFI, using
- /dev/sda as the device.
+
+
-
+
+ The NixOS installer doesn’t do any partitioning or formatting,
+ so you need to do that yourself.
+
+
+ The NixOS installer ships with multiple partitioning tools. The
+ examples below use parted, but also provides
+ fdisk, gdisk,
+ cfdisk, and cgdisk.
+
+
+ The recommended partition scheme differs depending if the
+ computer uses Legacy Boot or
+ UEFI.
+
+
+ UEFI (GPT)
- You can safely ignore parted's
- informational message about needing to update /etc/fstab.
+
+
-
-
-
+
+ Here's an example partition scheme for UEFI, using
+ /dev/sda as the device.
+
+
- Create a GPT partition table.
+ You can safely ignore parted's
+ informational message about needing to update /etc/fstab.
-
+
+
+
+
+ Create a GPT partition table.
+
+
# parted /dev/sda -- mklabel gpt
-
-
-
- Add the root partition. This will fill
- the disk except for the end part, where the swap will live,
- and the space left in front (512MiB) which will be used by
- the boot partition.
-
-
+
+
+
+ Add the root partition. This will
+ fill the disk except for the end part, where the swap will
+ live, and the space left in front (512MiB) which will be
+ used by the boot partition.
+
+
# parted /dev/sda -- mkpart primary 512MB -8GB
-
-
-
- Next, add a swap partition. The size
- required will vary according to needs, here a 8GB one is
- created.
-
-
+
+
+
+ Next, add a swap partition. The size
+ required will vary according to needs, here a 8GB one is
+ created.
+
+
# parted /dev/sda -- mkpart primary linux-swap -8GB 100%
-
+
+
+ The swap partition size rules are no different than for
+ other Linux distributions.
+
+
+
+
- The swap partition size rules are no different than for
- other Linux distributions.
+ Finally, the boot partition. NixOS by
+ default uses the ESP (EFI system partition) as its
+ /boot partition. It uses the
+ initially reserved 512MiB at the start of the disk.
-
-
-
-
- Finally, the boot partition. NixOS by
- default uses the ESP (EFI system partition) as its
- /boot partition. It uses the initially
- reserved 512MiB at the start of the disk.
-
-
+
# parted /dev/sda -- mkpart ESP fat32 1MB 512MB
# parted /dev/sda -- set 3 esp on
-
-
-
- Once complete, you can follow with
- .
-
-
-
- Legacy Boot (MBR)
-
- Here's an example partition scheme for Legacy Boot, using
- /dev/sda as the device.
-
-
+
+
- You can safely ignore parted's
- informational message about needing to update /etc/fstab.
+ Once complete, you can follow with
+ .
-
+
+
+ Legacy Boot (MBR)
+
+
+
+
+
+ Here's an example partition scheme for Legacy Boot, using
+ /dev/sda as the device.
+
+
+
+ You can safely ignore parted's
+ informational message about needing to update /etc/fstab.
+
+
+
+
+
+ Create a MBR partition table.
+
+
+# parted /dev/sda -- mklabel msdos
+
+
+
+
+ Add the root partition. This will
+ fill the the disk except for the end part, where the swap
+ will live.
+
+
+# parted /dev/sda -- mkpart primary 1MB -8GB
+
+
+
+
+ Set the root partition’s boot flag to on. This allows the
+ disk to be booted from.
+
+
+# parted /dev/sda -- set 1 boot on
+
+
+
+
+ Finally, add a swap partition. The
+ size required will vary according to needs, here a 8GiB
+ one is created.
+
+
+# parted /dev/sda -- mkpart primary linux-swap -8GB 100%
+
+
+
+ The swap partition size rules are no different than for
+ other Linux distributions.
+
+
+
+
+
+ Once complete, you can follow with
+ .
+
+
+
+ Formatting
+
+
+
+
+
+ Use the following commands:
+
+
+
+
+ For initialising Ext4 partitions:
+ mkfs.ext4. It is recommended that you
+ assign a unique symbolic label to the file system using
+ the option -L label, since this makes
+ the file system configuration independent from device
+ changes. For example:
+
+
+# mkfs.ext4 -L nixos /dev/sda1
+
+
+
+
+ For creating swap partitions: mkswap.
+ Again it’s recommended to assign a label to the swap
+ partition: -L label. For example:
+
+
+# mkswap -L swap /dev/sda2
+
+
+
+
+ UEFI systems
+
+
+ For creating boot partitions: mkfs.fat.
+ Again it’s recommended to assign a label to the boot
+ partition: -n label. For example:
+
+
+# mkfs.fat -F 32 -n boot /dev/sda3
+
+
+
+
+ For creating LVM volumes, the LVM commands, e.g.,
+ pvcreate, vgcreate,
+ and lvcreate.
+
+
+
+
+ For creating software RAID devices, use
+ mdadm.
+
+
+
+
+
+
+ Installing
+
+
+
+
- Create a MBR partition table.
+ Mount the target file system on which NixOS should be
+ installed on /mnt, e.g.
-# parted /dev/sda -- mklabel msdos
-
-
-
-
- Add the root partition. This will fill
- the the disk except for the end part, where the swap will
- live.
-
-
-# parted /dev/sda -- mkpart primary 1MB -8GB
-
-
-
-
- Set the root partition’s boot flag to on. This allows the
- disk to be booted from.
-
-
-# parted /dev/sda -- set 1 boot on
-
-
-
-
- Finally, add a swap partition. The size
- required will vary according to needs, here a 8GiB one is
- created.
-
-
-# parted /dev/sda -- mkpart primary linux-swap -8GB 100%
-
-
-
- The swap partition size rules are no different than for
- other Linux distributions.
-
-
-
-
-
- Once complete, you can follow with
- .
-
-
-
- Formatting
-
- Use the following commands:
-
-
-
-
- For initialising Ext4 partitions:
- mkfs.ext4. It is recommended that you
- assign a unique symbolic label to the file system using the
- option -L label, since this makes the
- file system configuration independent from device changes.
- For example:
-
-
-# mkfs.ext4 -L nixos /dev/sda1
-
-
-
-
- For creating swap partitions: mkswap.
- Again it’s recommended to assign a label to the swap
- partition: -L label. For example:
-
-
-# mkswap -L swap /dev/sda2
+# mount /dev/disk/by-label/nixos /mnt
@@ -310,322 +557,287 @@ OK
UEFI systems
- For creating boot partitions: mkfs.fat.
- Again it’s recommended to assign a label to the boot
- partition: -n label. For example:
+ Mount the boot file system on /mnt/boot,
+ e.g.
-# mkfs.fat -F 32 -n boot /dev/sda3
-
-
-
-
- For creating LVM volumes, the LVM commands, e.g.,
- pvcreate, vgcreate,
- and lvcreate.
-
-
-
-
- For creating software RAID devices, use
- mdadm.
-
-
-
-
-
-
- Installing
-
-
-
- Mount the target file system on which NixOS should be
- installed on /mnt, e.g.
-
-
-# mount /dev/disk/by-label/nixos /mnt
-
-
-
-
- UEFI systems
-
-
- Mount the boot file system on /mnt/boot,
- e.g.
-
-
# mkdir -p /mnt/boot
# mount /dev/disk/by-label/boot /mnt/boot
-
-
-
- If your machine has a limited amount of memory, you may want
- to activate swap devices now
- (swapon device). The installer (or rather,
- the build actions that it may spawn) may need quite a bit of
- RAM, depending on your configuration.
-
-
+
+
+
+ If your machine has a limited amount of memory, you may want
+ to activate swap devices now
+ (swapon device). The installer (or
+ rather, the build actions that it may spawn) may need quite
+ a bit of RAM, depending on your configuration.
+
+
# swapon /dev/sda2
-
-
-
- You now need to create a file
- /mnt/etc/nixos/configuration.nix that
- specifies the intended configuration of the system. This is
- because NixOS has a declarative
- configuration model: you create or edit a description of the
- desired configuration of your system, and then NixOS takes
- care of making it happen. The syntax of the NixOS
- configuration file is described in
- , while a list of
- available configuration options appears in
- . A minimal example is shown in
- Example: NixOS Configuration.
-
-
- The command nixos-generate-config can
- generate an initial configuration file for you:
-
-
+
+
+
+ You now need to create a file
+ /mnt/etc/nixos/configuration.nix that
+ specifies the intended configuration of the system. This is
+ because NixOS has a declarative
+ configuration model: you create or edit a description of the
+ desired configuration of your system, and then NixOS takes
+ care of making it happen. The syntax of the NixOS
+ configuration file is described in
+ , while a list of
+ available configuration options appears in
+ . A minimal example is shown in
+ Example: NixOS
+ Configuration.
+
+
+ The command nixos-generate-config can
+ generate an initial configuration file for you:
+
+
# nixos-generate-config --root /mnt
-
- You should then edit
- /mnt/etc/nixos/configuration.nix to suit
- your needs:
-
-
+
+ You should then edit
+ /mnt/etc/nixos/configuration.nix to suit
+ your needs:
+
+
# nano /mnt/etc/nixos/configuration.nix
-
- If you’re using the graphical ISO image, other editors may be
- available (such as vim). If you have
- network access, you can also install other editors – for
- instance, you can install Emacs by running
- nix-env -f '<nixpkgs>' -iA emacs.
-
-
-
-
- BIOS systems
-
-
-
- You must set the option
- to
- specify on which disk the GRUB boot loader is to be
- installed. Without it, NixOS cannot boot.
-
-
- If there are other operating systems running on the
- machine before installing NixOS, the
-
- option can be set to true to
- automatically add them to the grub menu.
-
-
-
-
-
- UEFI systems
-
-
-
- You must select a boot-loader, either system-boot or
- GRUB. The recommended option is systemd-boot: set the
- option
-
- to true.
- nixos-generate-config should do this
- automatically for new configurations when booted in UEFI
- mode.
-
-
- You may want to look at the options starting with
- boot.loader.efi
- and
- boot.loader.systemd-boot
- as well.
-
-
- If you want to use GRUB, set
- to
- nodev and
- to
- true.
-
-
- With system-boot, you should not need any special
- configuration to detect other installed systems. With
- GRUB, set
- to
- true, but this will only detect
- windows partitions, not other linux distributions. If
- you dual boot another linux distribution, use
- system-boot instead.
-
-
-
-
-
- If you need to configure networking for your machine the
- configuration options are described in
- . In particular, while wifi
- is supported on the installation image, it is not enabled by
- default in the configuration generated by
- nixos-generate-config.
-
-
- Another critical option is fileSystems,
- specifying the file systems that need to be mounted by NixOS.
- However, you typically don’t need to set it yourself, because
- nixos-generate-config sets it automatically
- in
- /mnt/etc/nixos/hardware-configuration.nix
- from your currently mounted file systems. (The configuration
- file hardware-configuration.nix is included
- from configuration.nix and will be
- overwritten by future invocations of
- nixos-generate-config; thus, you generally
- should not modify it.) Additionally, you may want to look at
- Hardware
- configuration for known-hardware at this point or after
- installation.
-
-
- Depending on your hardware configuration or type of file
- system, you may need to set the option
- boot.initrd.kernelModules to include the
- kernel modules that are necessary for mounting the root file
- system, otherwise the installed system will not be able to
- boot. (If this happens, boot from the installation media
- again, mount the target file system on
- /mnt, fix
- /mnt/etc/nixos/configuration.nix and
- rerun nixos-install.) In most cases,
- nixos-generate-config will figure out the
- required modules.
+ If you’re using the graphical ISO image, other editors may
+ be available (such as vim). If you have
+ network access, you can also install other editors – for
+ instance, you can install Emacs by running
+ nix-env -f '<nixpkgs>' -iA emacs.
-
-
-
-
- Do the installation:
-
-
+
+
+
+ BIOS systems
+
+
+
+ You must set the option
+ to
+ specify on which disk the GRUB boot loader is to be
+ installed. Without it, NixOS cannot boot.
+
+
+ If there are other operating systems running on the
+ machine before installing NixOS, the
+
+ option can be set to true to
+ automatically add them to the grub menu.
+
+
+
+
+
+ UEFI systems
+
+
+
+ You must select a boot-loader, either system-boot or
+ GRUB. The recommended option is systemd-boot: set the
+ option
+
+ to true.
+ nixos-generate-config should do
+ this automatically for new configurations when booted
+ in UEFI mode.
+
+
+ You may want to look at the options starting with
+ boot.loader.efi
+ and
+ boot.loader.systemd-boot
+ as well.
+
+
+ If you want to use GRUB, set
+ to
+ nodev and
+ to
+ true.
+
+
+ With system-boot, you should not need any special
+ configuration to detect other installed systems. With
+ GRUB, set
+ to
+ true, but this will only detect
+ windows partitions, not other linux distributions. If
+ you dual boot another linux distribution, use
+ system-boot instead.
+
+
+
+
+
+ If you need to configure networking for your machine the
+ configuration options are described in
+ . In particular, while wifi
+ is supported on the installation image, it is not enabled by
+ default in the configuration generated by
+ nixos-generate-config.
+
+
+ Another critical option is fileSystems,
+ specifying the file systems that need to be mounted by
+ NixOS. However, you typically don’t need to set it yourself,
+ because nixos-generate-config sets it
+ automatically in
+ /mnt/etc/nixos/hardware-configuration.nix
+ from your currently mounted file systems. (The configuration
+ file hardware-configuration.nix is
+ included from configuration.nix and will
+ be overwritten by future invocations of
+ nixos-generate-config; thus, you
+ generally should not modify it.) Additionally, you may want
+ to look at
+ Hardware
+ configuration for known-hardware at this point or
+ after installation.
+
+
+
+ Depending on your hardware configuration or type of file
+ system, you may need to set the option
+ boot.initrd.kernelModules to include
+ the kernel modules that are necessary for mounting the
+ root file system, otherwise the installed system will not
+ be able to boot. (If this happens, boot from the
+ installation media again, mount the target file system on
+ /mnt, fix
+ /mnt/etc/nixos/configuration.nix and
+ rerun nixos-install.) In most cases,
+ nixos-generate-config will figure out
+ the required modules.
+
+
+
+
+
+ Do the installation:
+
+
# nixos-install
-
- This will install your system based on the configuration you
- provided. If anything fails due to a configuration problem or
- any other issue (such as a network outage while downloading
- binaries from the NixOS binary cache), you can re-run
- nixos-install after fixing your
- configuration.nix.
-
-
- As the last step, nixos-install will ask
- you to set the password for the root user,
- e.g.
-
-
+
+ This will install your system based on the configuration you
+ provided. If anything fails due to a configuration problem
+ or any other issue (such as a network outage while
+ downloading binaries from the NixOS binary cache), you can
+ re-run nixos-install after fixing your
+ configuration.nix.
+
+
+ As the last step, nixos-install will ask
+ you to set the password for the root
+ user, e.g.
+
+
setting root password...
New password: ***
Retype new password: ***
-
+
+
+ For unattended installations, it is possible to use
+ nixos-install --no-root-passwd in order
+ to disable the password prompt entirely.
+
+
+
+
- For unattended installations, it is possible to use
- nixos-install --no-root-passwd in order
- to disable the password prompt entirely.
+ If everything went well:
-
-
-
-
- If everything went well:
-
-
+
# reboot
-
-
-
- You should now be able to boot into the installed NixOS. The
- GRUB boot menu shows a list of available
- configurations (initially just one). Every time you
- change the NixOS configuration (see
- Changing
- Configuration), a new item is added to the menu. This
- allows you to easily roll back to a previous configuration if
- something goes wrong.
-
-
- You should log in and change the root
- password with passwd.
-
-
- You’ll probably want to create some user accounts as well,
- which can be done with useradd:
-
-
+
+
+
+ You should now be able to boot into the installed NixOS. The
+ GRUB boot menu shows a list of available
+ configurations (initially just one). Every time
+ you change the NixOS configuration (see
+ Changing
+ Configuration), a new item is added to the menu. This
+ allows you to easily roll back to a previous configuration
+ if something goes wrong.
+
+
+ You should log in and change the root
+ password with passwd.
+
+
+ You’ll probably want to create some user accounts as well,
+ which can be done with useradd:
+
+
$ useradd -c 'Eelco Dolstra' -m eelco
$ passwd eelco
-
- You may also want to install some software. This will be
- covered in .
-
-
-
-
-
- Installation summary
-
- To summarise, Example:
- Commands for Installing NixOS on
- /dev/sda shows a typical sequence of
- commands for installing NixOS on an empty hard drive (here
- /dev/sda). Example:
- NixOS Configuration shows a corresponding configuration Nix
- expression.
-
-
-
- Example: Example partition schemes for
- NixOS on /dev/sda (MBR)
-
-
+
+ You may also want to install some software. This will be
+ covered in .
+
+
+
+
+
+ Installation summary
+
+
+
+
+
+ To summarise, Example:
+ Commands for Installing NixOS on
+ /dev/sda shows a typical sequence of
+ commands for installing NixOS on an empty hard drive (here
+ /dev/sda). Example:
+ NixOS Configuration shows a corresponding configuration
+ Nix expression.
+
+
+
+ Example: Example partition schemes for
+ NixOS on /dev/sda (MBR)
+
+
# parted /dev/sda -- mklabel msdos
# parted /dev/sda -- mkpart primary 1MiB -8GiB
# parted /dev/sda -- mkpart primary linux-swap -8GiB 100%
-
-
- Example: Example partition schemes for
- NixOS on /dev/sda (UEFI)
-
-
+
+
+ Example: Example partition schemes for
+ NixOS on /dev/sda (UEFI)
+
+
# parted /dev/sda -- mklabel gpt
# parted /dev/sda -- mkpart primary 512MiB -8GiB
# parted /dev/sda -- mkpart primary linux-swap -8GiB 100%
# parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB
# parted /dev/sda -- set 3 esp on
-
-
- Example: Commands for Installing NixOS on
- /dev/sda
-
-
- With a partitioned disk.
-
-
+
+
+ Example: Commands for Installing NixOS
+ on /dev/sda
+
+
+ With a partitioned disk.
+
+
# mkfs.ext4 -L nixos /dev/sda1
# mkswap -L swap /dev/sda2
# swapon /dev/sda2
@@ -638,11 +850,11 @@ $ passwd eelco
# nixos-install
# reboot
-
-
- Example: NixOS Configuration
-
-
+
+
+ Example: NixOS Configuration
+
+
{ config, pkgs, ... }: {
imports = [
# Include the results of the hardware scan.
@@ -661,6 +873,7 @@ $ passwd eelco
services.sshd.enable = true;
}
+ Additional installation notes
diff --git a/nixos/doc/manual/from_md/installation/obtaining.chapter.xml b/nixos/doc/manual/from_md/installation/obtaining.chapter.xml
index a922feda2536..d187adfc0c53 100644
--- a/nixos/doc/manual/from_md/installation/obtaining.chapter.xml
+++ b/nixos/doc/manual/from_md/installation/obtaining.chapter.xml
@@ -2,16 +2,15 @@
Obtaining NixOS
NixOS ISO images can be downloaded from the
- NixOS
- download page. There are a number of installation options. If
- you happen to have an optical drive and a spare CD, burning the
- image to CD and booting from that is probably the easiest option.
- Most people will need to prepare a USB stick to boot from.
- describes the preferred
- method to prepare a USB stick. A number of alternative methods are
- presented in the
- NixOS
- Wiki.
+ NixOS
+ download page. Follow the instructions in
+ to create a bootable USB
+ flash drive.
+
+
+ If you have a very old system that can’t boot from USB, you can burn
+ the image to an empty CD. NixOS might not work very well on such
+ systems.
As an alternative to installing NixOS yourself, you can get a
@@ -23,16 +22,16 @@
Using virtual appliances in Open Virtualization Format (OVF)
that can be imported into VirtualBox. These are available from
the
- NixOS
+ NixOS
download page.
- Using AMIs for Amazon’s EC2. To find one for your region and
- instance type, please refer to the
- list
- of most recent AMIs.
+ Using AMIs for Amazon’s EC2. To find one for your region, please
+ refer to the
+ download
+ page.
diff --git a/nixos/doc/manual/installation/installing-usb.section.md b/nixos/doc/manual/installation/installing-usb.section.md
index d893e22e6381..da32935a7a10 100644
--- a/nixos/doc/manual/installation/installing-usb.section.md
+++ b/nixos/doc/manual/installation/installing-usb.section.md
@@ -1,31 +1,72 @@
-# Booting from a USB Drive {#sec-booting-from-usb}
+# Booting from a USB flash drive {#sec-booting-from-usb}
-For systems without CD drive, the NixOS live CD can be booted from a USB
-stick. You can use the `dd` utility to write the image:
-`dd if=path-to-image of=/dev/sdX`. Be careful about specifying the correct
-drive; you can use the `lsblk` command to get a list of block devices.
+The image has to be written verbatim to the USB flash drive for it to be
+bootable on UEFI and BIOS systems. Here are the recommended tools to do that.
-::: {.note}
-::: {.title}
-On macOS
+## Creating bootable USB flash drive with a graphical tool {#sec-booting-from-usb-graphical}
+
+Etcher is a popular and user-friendly tool. It works on Linux, Windows and macOS.
+
+Download it from [balena.io](https://www.balena.io/etcher/), start the program,
+select the downloaded NixOS ISO, then select the USB flash drive and flash it.
+
+::: {.warning}
+Etcher reports errors and usage statistics by default, which can be disabled in
+the settings.
:::
-```ShellSession
-$ diskutil list
-[..]
-/dev/diskN (external, physical):
- #: TYPE NAME SIZE IDENTIFIER
-[..]
-$ diskutil unmountDisk diskN
-Unmount of all volumes on diskN was successful
-$ sudo dd if=nix.iso of=/dev/rdiskN bs=1M
-```
+An alternative is [USBImager](https://bztsrc.gitlab.io/usbimager),
+which is very simple and does not connect to the internet. Download the version
+with write-only (wo) interface for your system. Start the program,
+select the image, select the USB flash drive and click "Write".
-Using the \'raw\' `rdiskN` device instead of `diskN` completes in
-minutes instead of hours. After `dd` completes, a GUI dialog \"The disk
-you inserted was not readable by this computer\" will pop up, which can
-be ignored.
-:::
+## Creating bootable USB flash drive from a Terminal on Linux {#sec-booting-from-usb-linux}
-The `dd` utility will write the image verbatim to the drive, making it
-the recommended option for both UEFI and non-UEFI installations.
+1. Plug in the USB flash drive.
+2. Find the corresponding device with `lsblk`. You can distinguish them by
+ their size.
+3. Make sure all partitions on the device are properly unmounted. Replace `sdX`
+ with your device (e.g. `sdb`).
+
+ ```ShellSession
+ sudo umount /dev/sdX*
+ ```
+
+4. Then use the `dd` utility to write the image to the USB flash drive.
+
+ ```ShellSession
+ sudo dd if= of=/dev/sdX bs=4M conv=fsync
+ ```
+
+## Creating bootable USB flash drive from a Terminal on macOS {#sec-booting-from-usb-macos}
+
+1. Plug in the USB flash drive.
+2. Find the corresponding device with `diskutil list`. You can distinguish them
+ by their size.
+3. Make sure all partitions on the device are properly unmounted. Replace `diskX`
+ with your device (e.g. `disk1`).
+
+ ```ShellSession
+ diskutil unmountDisk diskX
+ ```
+
+4. Then use the `dd` utility to write the image to the USB flash drive.
+
+ ```ShellSession
+ sudo dd if= of=/dev/rdiskX bs=4m
+ ```
+
+ After `dd` completes, a GUI dialog \"The disk
+ you inserted was not readable by this computer\" will pop up, which can
+ be ignored.
+
+ ::: {.note}
+ Using the \'raw\' `rdiskX` device instead of `diskX` with dd completes in
+ minutes instead of hours.
+ :::
+
+5. Eject the disk when it is finished.
+
+ ```ShellSession
+ diskutil eject /dev/diskX
+ ```
diff --git a/nixos/doc/manual/installation/installing.chapter.md b/nixos/doc/manual/installation/installing.chapter.md
index b1e58b14b783..44e7e29421d6 100644
--- a/nixos/doc/manual/installation/installing.chapter.md
+++ b/nixos/doc/manual/installation/installing.chapter.md
@@ -1,30 +1,143 @@
# Installing NixOS {#sec-installation}
-## Booting the system {#sec-installation-booting}
+## Booting from the install medium {#sec-installation-booting}
+
+To begin the installation, you have to boot your computer from the install drive.
+
+1. Plug in the install drive. Then turn on or restart your computer.
+
+2. Open the boot menu by pressing the appropriate key, which is usually shown
+ on the display on early boot.
+ Select the USB flash drive (the option usually contains the word "USB").
+ If you choose the incorrect drive, your computer will likely continue to
+ boot as normal. In that case restart your computer and pick a
+ different drive.
+
+ ::: {.note}
+ The key to open the boot menu is different across computer brands and even
+ models. It can be F12, but also F1,
+ F9, F10, Enter, Del,
+ Esc or another function key. If you are unsure and don't see
+ it on the early boot screen, you can search online for your computers
+ brand, model followed by "boot from usb".
+ The computer might not even have that feature, so you have to go into the
+ BIOS/UEFI settings to change the boot order. Again, search online for
+ details about your specific computer model.
+
+ For Apple computers with Intel processors press and hold the ⌥
+ (Option or Alt) key until you see the boot menu. On Apple silicon press
+ and hold the power button.
+ :::
+
+ ::: {.note}
+ If your computer supports both BIOS and UEFI boot, choose the UEFI option.
+ :::
+
+ ::: {.note}
+ If you use a CD for the installation, the computer will probably boot from
+ it automatically. If not, choose the option containing the word "CD" from
+ the boot menu.
+ :::
+
+3. Shortly after selecting the appropriate boot drive, you should be
+ presented with a menu with different installer options. Leave the default
+ and wait (or press Enter to speed up).
+
+4. The graphical images will start their corresponding desktop environment
+ and the graphical installer, which can take some time. The minimal images
+ will boot to a command line. You have to follow the instructions in
+ [](#sec-installation-manual) there.
+
+## Graphical Installation {#sec-installation-graphical}
+
+The graphical installer is recommended for desktop users and will guide you
+through the installation.
+
+1. In the "Welcome" screen, you can select the language of the Installer and
+ the installed system.
+
+ ::: {.tip}
+ Leaving the language as "American English" will make it easier to search for
+ error messages in a search engine or to report an issue.
+ :::
+
+2. Next you should choose your location to have the timezone set correctly.
+ You can actually click on the map!
+
+ ::: {.note}
+ The installer will use an online service to guess your location based on
+ your public IP address.
+ :::
+
+3. Then you can select the keyboard layout. The default keyboard model should
+ work well with most desktop keyboards. If you have a special keyboard or
+ notebook, your model might be in the list. Select the language you are most
+ comfortable typing in.
+
+4. On the "Users" screen, you have to type in your display name, login name
+ and password. You can also enable an option to automatically login to the
+ desktop.
+
+5. Then you have the option to choose a desktop environment. If you want to
+ create a custom setup with a window manager, you can select "No desktop".
+
+ ::: {.tip}
+ If you don't have a favorite desktop and don't know which one to choose,
+ you can stick to either GNOME or Plasma. They have a quite different
+ design, so you should choose whichever you like better.
+ They are both popular choices and well tested on NixOS.
+ :::
+
+6. You have the option to allow unfree software in the next screen.
+
+7. The easiest option in the "Partitioning" screen is "Erase disk", which will
+ delete all data from the selected disk and install the system on it.
+ Also select "Swap (with Hibernation)" in the dropdown below it.
+ You have the option to encrypt the whole disk with LUKS.
+
+ ::: {.note}
+ At the top left you see if the Installer was booted with BIOS or UEFI. If
+ you know your system supports UEFI and it shows "BIOS", reboot with the
+ correct option.
+ :::
+
+ ::: {.warning}
+ Make sure you have selected the correct disk at the top and that no
+ valuable data is still on the disk! It will be deleted when
+ formatting the disk.
+ :::
+
+8. Check the choices you made in the "Summary" and click "Install".
+
+ ::: {.note}
+ The installation takes about 15 minutes. The time varies based on the
+ selected desktop environment, internet connection speed and disk write speed.
+ :::
+
+9. When the install is complete, remove the USB flash drive and
+ reboot into your new system!
+
+## Manual Installation {#sec-installation-manual}
NixOS can be installed on BIOS or UEFI systems. The procedure for a UEFI
-installation is by and large the same as a BIOS installation. The
-differences are mentioned in the steps that follow.
+installation is broadly the same as for a BIOS installation. The differences
+are mentioned in the following steps.
-The installation media can be burned to a CD, or now more commonly,
-"burned" to a USB drive (see [](#sec-booting-from-usb)).
+The NixOS manual is available by running `nixos-help` in the command line
+or from the application menu in the desktop environment.
-The installation media contains a basic NixOS installation. When it's
-finished booting, it should have detected most of your hardware.
-
-The NixOS manual is available by running `nixos-help`.
+To have access to the command line on the graphical images, open
+Terminal (GNOME) or Konsole (Plasma) from the application menu.
You are logged-in automatically as `nixos`. The `nixos` user account has
an empty password so you can use `sudo` without a password:
+
```ShellSession
$ sudo -i
```
-If you downloaded the graphical ISO image, you can run `systemctl
-start display-manager` to start the desktop environment. If you want
-to continue on the terminal, you can use `loadkeys` to switch to your
-preferred keyboard layout. (We even provide neo2 via `loadkeys de
-neo`!)
+You can use `loadkeys` to switch to your preferred keyboard layout.
+(We even provide neo2 via `loadkeys de neo`!)
If the text is too small to be legible, try `setfont ter-v32n` to
increase the font size.
@@ -33,7 +146,8 @@ To install over a serial port connect with `115200n8` (e.g.
`picocom -b 115200 /dev/ttyUSB0`). When the bootloader lists boot
entries, select the serial console boot entry.
-### Networking in the installer {#sec-installation-booting-networking}
+### Networking in the installer {#sec-installation-manual-networking}
+[]{#sec-installation-booting-networking}
The boot process should have brought up networking (check `ip
a`). Networking is necessary for the installer, since it will
@@ -100,7 +214,8 @@ placed by mounting the image on a different machine). Alternatively you
must set a password for either `root` or `nixos` with `passwd` to be
able to login.
-## Partitioning and formatting {#sec-installation-partitioning}
+### Partitioning and formatting {#sec-installation-manual-partitioning}
+[]{#sec-installation-partitioning}
The NixOS installer doesn't do any partitioning or formatting, so you
need to do that yourself.
@@ -112,7 +227,8 @@ below use `parted`, but also provides `fdisk`, `gdisk`, `cfdisk`, and
The recommended partition scheme differs depending if the computer uses
*Legacy Boot* or *UEFI*.
-### UEFI (GPT) {#sec-installation-partitioning-UEFI}
+#### UEFI (GPT) {#sec-installation-manual-partitioning-UEFI}
+[]{#sec-installation-partitioning-UEFI}
Here\'s an example partition scheme for UEFI, using `/dev/sda` as the
device.
@@ -158,9 +274,10 @@ update /etc/fstab.
```
Once complete, you can follow with
-[](#sec-installation-partitioning-formatting).
+[](#sec-installation-manual-partitioning-formatting).
-### Legacy Boot (MBR) {#sec-installation-partitioning-MBR}
+#### Legacy Boot (MBR) {#sec-installation-manual-partitioning-MBR}
+[]{#sec-installation-partitioning-MBR}
Here\'s an example partition scheme for Legacy Boot, using `/dev/sda` as
the device.
@@ -202,9 +319,10 @@ update /etc/fstab.
:::
Once complete, you can follow with
-[](#sec-installation-partitioning-formatting).
+[](#sec-installation-manual-partitioning-formatting).
-### Formatting {#sec-installation-partitioning-formatting}
+#### Formatting {#sec-installation-manual-partitioning-formatting}
+[]{#sec-installation-partitioning-formatting}
Use the following commands:
@@ -239,7 +357,8 @@ Use the following commands:
- For creating software RAID devices, use `mdadm`.
-## Installing {#sec-installation-installing}
+### Installing {#sec-installation-manual-installing}
+[]{#sec-installation-installing}
1. Mount the target file system on which NixOS should be installed on
`/mnt`, e.g.
@@ -410,7 +529,8 @@ Use the following commands:
You may also want to install some software. This will be covered in
[](#sec-package-management).
-## Installation summary {#sec-installation-summary}
+### Installation summary {#sec-installation-manual-summary}
+[]{#sec-installation-summary}
To summarise, [Example: Commands for Installing NixOS on `/dev/sda`](#ex-install-sequence)
shows a typical sequence of commands for installing NixOS on an empty hard
diff --git a/nixos/doc/manual/installation/obtaining.chapter.md b/nixos/doc/manual/installation/obtaining.chapter.md
index 832ec6146a9d..a72194ecf985 100644
--- a/nixos/doc/manual/installation/obtaining.chapter.md
+++ b/nixos/doc/manual/installation/obtaining.chapter.md
@@ -1,24 +1,21 @@
# Obtaining NixOS {#sec-obtaining}
NixOS ISO images can be downloaded from the [NixOS download
-page](https://nixos.org/nixos/download.html). There are a number of
-installation options. If you happen to have an optical drive and a spare
-CD, burning the image to CD and booting from that is probably the
-easiest option. Most people will need to prepare a USB stick to boot
-from. [](#sec-booting-from-usb) describes the preferred method to
-prepare a USB stick. A number of alternative methods are presented in
-the [NixOS Wiki](https://nixos.wiki/wiki/NixOS_Installation_Guide#Making_the_installation_media).
+page](https://nixos.org/download.html#nixos-iso). Follow the instructions in
+[](#sec-booting-from-usb) to create a bootable USB flash drive.
+
+If you have a very old system that can't boot from USB, you can burn the image
+to an empty CD. NixOS might not work very well on such systems.
As an alternative to installing NixOS yourself, you can get a running
NixOS system through several other means:
- Using virtual appliances in Open Virtualization Format (OVF) that
can be imported into VirtualBox. These are available from the [NixOS
- download page](https://nixos.org/nixos/download.html).
+ download page](https://nixos.org/download.html#nixos-virtualbox).
-- Using AMIs for Amazon's EC2. To find one for your region and
- instance type, please refer to the [list of most recent
- AMIs](https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/virtualisation/ec2-amis.nix).
+- Using AMIs for Amazon's EC2. To find one for your region, please refer
+ to the [download page](https://nixos.org/download.html#nixos-amazon).
- Using NixOps, the NixOS-based cloud deployment tool, which allows
you to provision VirtualBox and EC2 NixOS instances from declarative