GRUB runs after the firmware and before the kernel. It finds the kernel, loads the initramfs, passes the kernel its parameters, and hands over. When a machine stops booting, GRUB is either the cause or the place you fix it.

The configuration, and where not to edit

/boot/grub/grub.cfg, or /boot/grub2/grub.cfg on Fedora, is generated. It says so at the top. Editing it works until the next kernel update regenerates it and throws your changes away.

The real inputs are:

• /etc/default/grub for settings
• /etc/grub.d/ for scripts that build menu entries

After changing either:

sudo update-grub                                   # Debian and Ubuntu
sudo grub2-mkconfig -o /boot/grub2/grub.cfg        # Fedora
sudo grub-mkconfig -o /boot/grub/grub.cfg          # Arch

Settings worth knowing

sudo nano /etc/default/grub

GRUB_TIMEOUT=5
GRUB_TIMEOUT_STYLE=menu
GRUB_DEFAULT=0
GRUB_CMDLINE_LINUX_DEFAULT="quiet splash"
GRUB_CMDLINE_LINUX=""
GRUB_DISABLE_OS_PROBER=false

GRUB_TIMEOUT_STYLE=menu with a timeout of a few seconds makes the menu visible, which you want on any machine you might need to recover.

GRUB_DISABLE_OS_PROBER=false matters for dual boot, since recent GRUB versions disable OS detection by default and Windows stops appearing in the menu.

GRUB_CMDLINE_LINUX_DEFAULT applies to normal entries; GRUB_CMDLINE_LINUX applies to recovery entries too.

Kernel parameters

Test before committing. At the boot menu, highlight an entry and press e, edit the line starting linux, and press Ctrl-X to boot with it. That applies once and survives nothing, which is exactly what you want while experimenting.

Parameters that come up:

• nomodeset stops early kernel mode setting, a diagnostic for a black screen with a graphics driver problem
• quiet hides boot messages, splash shows a graphical boot screen. Remove both to see what is failing
• single or systemd.unit=rescue.target boots to single user mode
• init=/bin/bash gets a root shell with almost nothing started, for when everything else fails
• amd_iommu=on or intel_iommu=on for PCI passthrough
• mitigations=off disables CPU vulnerability mitigations, which recovers performance and is a genuine security tradeoff

Check what the running system used:

cat /proc/cmdline

Recovering a broken boot

GRUB rescue prompt. GRUB started but cannot find its files.

grub rescue> ls
grub rescue> set root=(hd0,gpt2)
grub rescue> set prefix=(hd0,gpt2)/boot/grub
grub rescue> insmod normal
grub rescue> normal

Then reinstall properly once booted.

Reinstalling from a live USB. The standard repair:

sudo mount /dev/sda2 /mnt                  # root
sudo mount /dev/sda1 /mnt/boot/efi         # EFI, on UEFI systems
for d in dev proc sys run; do sudo mount --bind /$d /mnt/$d; done
sudo chroot /mnt

grub-install /dev/sda                      # BIOS
grub-install --target=x86_64-efi --efi-directory=/boot/efi   # UEFI
update-grub
exit

Our chroot rescue guide covers this in more detail.

After a Windows install. Windows writes its own bootloader and sets itself first in the UEFI boot order. Nothing is broken; the order changed. Reinstall GRUB as above, or fix the order with efibootmgr:

sudo efibootmgr -v
sudo efibootmgr -o 0002,0000

systemd-boot

On UEFI systems with a straightforward setup, systemd-boot is a simpler alternative. It reads a directory of small text files rather than generating a large script.

# /boot/loader/entries/arch.conf
title   Arch Linux
linux   /vmlinuz-linux
initrd  /initramfs-linux.img
options root=UUID=... rw quiet

It cannot do BIOS boot, cannot read filesystems other than the EFI partition, and cannot handle an encrypted /boot. Within those limits it is easier to reason about, and Arch and several others support it directly.

Secure Boot

With Secure Boot on, the bootloader and kernel must be signed by a key the firmware trusts. Major distributions ship signed shims that handle this.

Where it bites is third-party kernel modules: NVIDIA drivers, VirtualBox, ZFS. An unsigned module is refused, which looks like the module simply failing to load. Either enrol your own key with MOK or turn Secure Boot off. Our Secure Boot explainer covers the tradeoff.

Frequently Asked Questions

Why should I not edit grub.cfg directly?

Because it is generated. Any kernel update, package upgrade, or run of update-grub regenerates it and discards your changes. Edit /etc/default/grub or add a script in /etc/grub.d/ instead, then regenerate.

How do I add a kernel parameter permanently?

Append it to GRUB_CMDLINE_LINUX_DEFAULT in /etc/default/grub, then run update-grub on Debian and Ubuntu or grub2-mkconfig on Fedora. Test it first by editing the entry at the boot menu with e, which applies for one boot only.

How do I get to the GRUB menu if it does not appear?

Hold Shift on BIOS systems or press Esc repeatedly on UEFI during boot. To make it always appear, set GRUB_TIMEOUT_STYLE to menu and GRUB_TIMEOUT to a few seconds in /etc/default/grub.

What is the difference between GRUB and systemd-boot?

GRUB supports BIOS and UEFI, many filesystems, and complex setups including encrypted boot. systemd-boot is UEFI only and deliberately minimal, reading a directory of small config files. systemd-boot is simpler when your setup is simple.

How do I repair GRUB after installing Windows?

Boot a live USB, mount your root filesystem and EFI partition, chroot in, and reinstall GRUB. Windows installs its own bootloader and takes over the boot order, which is a configuration change rather than damage.

What does the nomodeset parameter do?

It stops the kernel setting the graphics mode early, so the GPU driver does not take over during boot. It is a diagnostic for a black screen after boot, and it means you have a graphics driver problem rather than being a fix in itself.