kernelstub

Automatic kernel EFI stub manager

TLDR

Print the current configuration

$ sudo kernelstub -p

Copy kernel and initrd to ESP and set up NVRAM boot entry

$ sudo kernelstub

Set kernel boot options

$ sudo kernelstub -o "quiet splash"

Add a kernel boot option without replacing existing ones

$ sudo kernelstub -a "nomodeset"

Remove a kernel boot option

$ sudo kernelstub -d "quiet"

Simulate actions without making changes (dry run)

$ sudo kernelstub -c

SYNOPSIS

kernelstub [-h] [-c] [-p] [-e ESPPATH] [**-r** ROOTPATH] [-k KERNELPATH] [**-i** INITRDPATH] [-o OPTIONS] [-a OPTIONS] [-d OPTIONS] [-g LOGFILE_] [-l] [-n] [-s] [-m] [-f] [-v]

kernelstub is an automatic EFI System Partition (ESP) manager for booting Linux on UEFI systems. It copies the current kernel and initramfs images to the ESP so they are discoverable by EFI firmware and boot loaders, and sets up NVRAM boot menu entries for direct kernel booting (EFI stub booting).The tool automatically updates these entries when new kernel versions are installed. It can create systemd-boot compatible loader configurations and manages kernel boot parameters persistently via configuration files. It is primarily used on Pop!_OS, which uses systemd-boot instead of GRUB as its default bootloader.

PARAMETERS

-h, --help

Display help text and exit.

-c, --dry-run

Simulate all actions without actually performing them.

-p, --print-config

Print the current configuration and exit.

-e PATH, --esp-path PATH

Manually specify the path to the EFI System Partition (default: /boot/efi).

-r PATH, --root-path PATH

The path where the root filesystem to use is mounted.

-k PATH, --kernel-path PATH

The path to the kernel image.

-i PATH, --initrd-path PATH

The path to the initrd image.

-o OPTIONS, --options OPTIONS

Set the complete kernel boot options (saves to config).

-a OPTIONS, --add-options OPTIONS

Add boot options to the configuration if not already present.

-d OPTIONS, --delete-options OPTIONS

Remove boot options from the configuration if present.

-g FILE, --log-file FILE

Path to the log file (default: /var/log/kernelstub.log).

-l, --loader

Create a systemd-boot compatible loader configuration (saves to config).

-n, --no-loader

Turn off creating loader configuration.

-s, --stub

Set up NVRAM entries for the copied kernel (saves to config).

-m, --manage-only

Only copy entries to ESP, do not set up NVRAM entries (saves to config).

-f, --force-update

Forcibly update loader.conf to set the new entry as default.

-v, --verbose

Increase verbosity. Use -vv for debug output.

CONFIGURATION

Configuration stored in /etc/kernelstub/configuration (auto-created if missing). The distributor template lives at /etc/default/kernelstub (read-only). A sample config is provided at /etc/kernelstub/SAMPLE. The -o, -l, -s, and -m flags persist their values to the config file, affecting future invocations.

CAVEATS

Must be run as root (exit code 176 if not). UEFI-only — has no purpose on legacy BIOS systems. The -f flag can overwrite another OS's boot configuration on dual-boot systems. Command-line options override configuration file settings, and some flags (-o, -l, -s, -m) persist changes to the config file.

HISTORY

kernelstub was created by Ian Santopietro in 2017 to simplify and automate EFI stub booting on Linux. Written in Python 3, it was developed in the context of Pop!_OS at System76, which uses systemd-boot as its default bootloader. The project is maintained under the pop-os organization on GitHub.