Bootloader

This article or section needs expansion.

Reason: Explain what the bootloader does and which bootloader exists. Also explain Legacy Boot vs. UEFI and bootloaders for ARM platforms (with links) (Discuss in Talk:Bootloader#)
Please consult the pedia article metapage for guidelines on contributing.

FAQ

Am I booted in Legacy or UEFI?

The following command will print which boot mode you are using. This can be used on the NixOS installation image to determine which steps to follow in the guide.

[ -d /sys/firmware/efi/efivars ] && echo "UEFI" || echo "Legacy"

How do I remove older generations from the bootloader?

First, collect garbages in your system, then rebuild. The scripts will collect leftover files.

The first command, in the example below, removes everything older than 14 days.

sudo nix-collect-garbage --delete-older-than 14d 
sudo nixos-rebuild boot

Limiting amount of entries with grub

The grub module has an option to limit the number of configurations made available in the boot partition, boot.loader.grub.configurationLimit. Setting this to a lower amount than the default may help reduce the occasions where too many different kernels and initrds are added to the /boot partition or ESP.

Keeping kernels/initrd on the main partition

For these instructions, GRUB will be required; systemd-boot cannot reference boot files from the root partition. This will differ from the default expectation of NixOS on EFI, where /boot/ is the ESP.

/etc/nixos/hardware-configuration.nix

fileSystems."/boot/efi" = ... # ← mount your ESP here instead of at /boot/.

/etc/nixos/configuration.nix

boot.loader = {
  efi = {
    canTouchEfiVariables = true;
    efiSysMountPoint = "/boot/efi"; # ← use the same mount point here.
  };
  grub = {
     efiSupport = true;
     #efiInstallAsRemovable = true; # in case canTouchEfiVariables doesn't work for your system
     device = "nodev";
  };
};

Troubleshooting

Re-installing the bootloader

• Something happened, and the bootloader doesn't work as expected.
• The ESP was re-made and nothing was kept
• The ESP wasn't mounted and I want to re-generate the menu entries

Booting from the installation media, mount the root partition, and the boot partition under /mnt. Next, bind system virtual file systems under /mnt. Finally, run the command that the installer would run. This will re-install the bootloader.

mount /dev/[root partition] /mnt
mount /dev/[boot partition] /mnt/boot
for i in dev proc sys; do mount --rbind /$i /mnt/$i; done
NIXOS_INSTALL_BOOTLOADER=1 chroot /mnt \
    /nix/var/nix/profiles/system/bin/switch-to-configuration boot

New generations are not in the boot menu

The most common cause for this situation is when the ESP isn't mounted where NixOS expects it to be on UEFI systems. NixOS assumes the ESP is mounted under /boot and that it is on the ESP that NixOS will install the files needed for the boot process for UEFI systems. This issue should affect all supported UEFI bootloaders equally for NixOS.

The usual fix for this problem is to add the missing entry for fileSystems."/boot" in hardware-configuration.nix (or where your mount points are defined).

If for some reason it is impossible to boot the existing generations, follow the steps in #Re-installing the bootloader to re-generate the menu entries, then boot in your system to add the missing configuration. The next generations should work as expected in your bootloader.

Wrangling recalcitrant UEFI implementations

Some UEFI implementations are just bad™. Some symptoms include:

• Losing bootloader configuration choices either randomly, or on disk disconnection.
• Not being able to manually edit the bootloader configuration.
• Not being able to save the bootloader configuration.
• Not being able to boot arbitrary bootloader configuration.

For those problematic EFI setup, or for a portable NixOS setup, it is possible to make use of the default path of the OS loader.

• For an x86_64 computer, this path is /EFI/BOOT/BOOTX64.EFI. Try this one first.
• For extremely problematic EFI implementations, an alternative path can be used, the default Windows bootloader location: /EFI/Microsoft/Boot/bootmgfw.efi.

As a recommendation, you can either copy the default NixOS bootloader (which will be in the /EFI/NixOS-boot/ folder) or install an secondary bootloader like rEFInd. A copied NixOS bootloader will not be updated by the NixOS configuration. Using a secondary bootloader will add an intermediary step during the boot process, which can be customized to be as short as wanted, but should allow selecting EFI programs, even on different disks.

Alternatively, when using grub, using the boot.loader.grub.efiInstallAsRemovable option will install the bootloader at the default /EFI/BOOT/BOOTX64.EFI location.

---