From Gentoo Wiki
Jump to:navigation Jump to:search

efibootmgr is a tool for managing UEFI boot entries.

It is not a bootloader. It is a tool that interacts with the EFI firmware of the system, which itself is acting as a boot manager. Using efibootmgr boot entries can be created, reshuffled and removed.



CONFIG_EFIVAR_FS support needs to be enabled.

It is not possible to use efivarfs without the EFI runtime services, which (in case they have been disabled by default, i.e. CONFIG_EFI_DISABLE_RUNTIME=y) can also be enabled by the kernel command-line option efi=runtime.


The sys-boot/efibootmgr package does not have any USE flags. All that is needed is to install it:

root #emerge --ask sys-boot/efibootmgr


EFI vars

In order to successfully use efibootmgr the EFI variables filesystem must be accessible. This requires that the system has been booted in EFI mode (and not through the firmware's MBR mode) as otherwise the EFI variables themselves cannot be accessed. If the system is in MBR mode, reboot and do what is necessary in order to tell the system firmware to boot in EFI mode. Usually this involved either changing an option in the firmware's settings or selecting an EFI boot entry in the system's boot menu.

When the system is in EFI mode, run the following command to check for the existence of a mounted efivarfs:

root #mount | grep efivars
efivarfs on /sys/firmware/efi/efivars type efivarfs (ro,relatime)

It is mounted read-only (ro) through the sysfs init script), so it needs to be remounted read-write (rw) manually using the following command:

root #mount -o remount,rw -t efivarfs efivarfs /sys/firmware/efi/efivars


If an EFI System Partition (ESP) does not exist, one needs to be created, see EFI System Partition.


Listing boot entries

When using an older version of efibootmgr the option --verbose or -v is needed:

root #efibootmgr
BootCurrent: 0002
Timeout: 3 seconds
BootOrder: 0003,0003,0002,0000,0004
Boot0000* CD/DVD Drive  BIOS(3,0,00)
Boot0001* Hard Drive    BIOS(2,0,00)
Boot0002* Gentoo        HD(1,800,61800,6d98f360-cb3e-4727-8fed-5ce0c040365d)File(\EFI\boot\bootx64.efi)
Boot0003* Hard Drive    BIOS(2,0,00)P0: ST1500DM003-9YN16G

Creating a boot entry

To create an EFI boot entry, a couple of arguments are passed to efibootmgr:

  • --create or -c to create a new entry;
  • --part or -p followed by the partition number on which the EFI System Partition is hosted;
  • --disk or -d followed by the disk on which the EFI System Partition is hosted;
  • --label or -L followed by the label to use as the boot entry;
  • --loader or -l followed by the path of the EFI image to boot
The path of the EFI image to boot must use \ (backslash) instead of / (forward slash) as path separator.
Additionally, if the ESP was already created by another OS, it might be named differently than /efi/EFI. If an ESP was created by another OS, begin the EFI Boot entry using this directory name, which immediately follows /efi.

Below are some examples of how a UEFI entry can be created. If this is the folder structure:

root #tree /efi/ -L 3
└── EFI
    ├── Grub
    │   └── grubx64.efi
    └── Gentoo
        └── bzImage.efi

then the loader paths will be:

root #efibootmgr -c -L "Grub" -l '\EFI\Grub\grubx64.efi'
root #efibootmgr -c -L "Gentoo" -l '\EFI\Gentoo\bzImage.efi'

For instance:

root #efibootmgr -c -d /dev/sda -p 2 -L "Gentoo" -l '\efi\boot\bootx64.efi'

It is also possible to add parameters – maybe not supported by all UEFI implementations[1] - to the kernel's command line:

root #efibootmgr -c -d /dev/sda -p 2 -L "Gentoo" -l '\efi\boot\bootx64.efi' -u 'root=/dev/sda3 initrd=\efi\boot\initramfs.img quiet'

Optionally, additional kernels can be installed and made known to the UEFI firmware. This is especially useful when wanting to test more kernels or to dual-boot with another operating system. These will be shown in the boot selection prompt, normally after a keyboard hotkey is pressed at the right time during system initialization. The latest added entry always gets highest boot priority, so it will be default. If the hotkey combination is unknown, search for official documentation from the computer manufacturer. This information is usually not difficult to find.

Deleting a boot entry

Before deleting an entry, first figure out what ID the entry has.

To delete the Gentoo entry as shown above (which has Boot0002 as the identifier), ask efibootmgr to delete the entry with id 2, passing the arguments --bootnum or -b with the identifier, and --delete-bootnum or -B to delete the entry:

root #efibootmgr -b 2 -B 2

Removable media

EFI bootloaders on removable media are not configured as boot entries, so tools like efibootmgr are not required. Instead the computer firmware identifies removable boot options by looking for a predefined file name unique to the system architecture in use, in a predefined path.[2]

Some (U)EFI implementations support the use of the removable media boot path as a fallback on internal drives.[3] This is against specification and should be avoided, but may help on a system with a buggy (U)EFI. Only one such fallback bootloader is possible on a specific system (i.e. architecture), due to the standardized boot path and file names.

Architecture Abbreviation File name PE executable machine type
x86 32-bit IA-32 \efi\boot\bootia32.efi 0x14c
x86-64 x64 \efi\boot\bootx64.efi 0x8664
Itanium IA-64 \efi\boot\bootia64.efi 0x200
ARM 32-bit AArch32 \efi\boot\bootarm.efi 0x01c2
ARM 64-bit AArch64 \efi\boot\bootaa64.efi 0xAA64
RISC-V 32-bit \efi\boot\bootriscv32.efi 0x5032
RISC-V 64-bit \efi\boot\bootriscv64.efi 0x5064
RISC-V 128-bit \efi\boot\bootriscv128.efi 0x5128
Loongson 32-bit LoongArch32 \efi\boot\bootloongarch32.efi 0x6232
Loongson 64-bit LoongArch64 \efi\boot\bootloongarch64.efi 0x6264
To boot from removable media, the firmware has to look for compatible bootloaders on supported devices, which can be configured in the firmware setup. Like most firmwares, (U)EFI provides a hotkey to show a boot selection (formally known as "BIOS Boot Selection" or BBS), otherwise (U)EFI will use the configured default boot entry. However, a buggy (U)EFI may default to the removable media boot path even on internal drives.

To use the removable media boot path it is sufficient to copy the EFI bootloader to the required path and file name. Should the firmware make use of this fallback, this may also remove the ability to select between configured boot entries, meaning that boot options (as listed with efibootmgr) through (U)EFI will not work. Even though every EFI bootloader can be used as fallback, it may be advisable to use a boot manager that itself has the ability to select between boot options, such as GRUB. From the above example for x64 (amd64):

root #cp /efi/EFI/Grub/grubx64.efi /efi/EFI/boot/bootx64.efi
The FAT file system of the EFI System Partition is not case-sensitive, but case-preserving (VFAT), while Unix and Linux is strictly case-sensitive at all times. Because of this, the path /efi/EFI/boot/bootx64.efi may not work on all systems, as it could be using capital letters, e.g. /efi/EFI/BOOT or /efi/EFI/Boot; the same goes for bootx64.efi. Running tree -L 3 /efi, when the ESP is mounted under /efi, will show the names in use on the individual system, to which the above command has to be changed accordingly.
The fallback bootloader is not automatically updated! Every time e.g. GRUB is re-installed (like after a version update, which may contain security fixes), it has to be copied to the fallback boot path again, overwriting (updating) the previous version!

The boot manager included in systemd, systemd-boot (formally Gummiboot), will automatically install to the removable media boot path. When sys-apps/systemd with the boot USE flag is updated, it is necessary to run bootctl again in order to update both bootloader files.

root #bootctl update



root #emerge --ask --depclean --verbose sys-boot/efibootmgr

See also