Limine

Related articles
Arch boot process
Master Boot Record
GUID Partition Table
Unified Extensible Firmware Interface
Limine
is an advanced, portable, multiprotocol
boot loader
originally developed as the reference implementation for the Limine boot protocol, but also supporting the ability to boot Linux as well as to chainload other boot loaders.
Note
In the entire article
esp
denotes the mountpoint of the
EFI system partition
aka ESP.
Supported file systems
Limine
supports
FAT12
,
FAT16
,
FAT32
and
ISO9660
. The list of supported file systems is intentionally limited per Limine's
design philosophy
.
Note
This does not mean that Limine cannot boot an OS which uses any other file system for its root; it just means that the kernel, initramfs, and any other files needed at boot will have to reside on a FAT partition (such as the ESP on UEFI systems).
Installation
Install
the
limine
package.
Follow the instructions in
#Deploying the boot loader
and
#Configuration
.
Deploying the boot loader
UEFI systems
Note
If installing on a system with a 32-bit UEFI, substitute the
BOOTX64.EFI
filename with
BOOTIA32.EFI
.
Deploying Limine on UEFI systems involves copying the
/usr/share/limine/BOOTX64.EFI
file to the EFI system partition, and to make the UEFI BIOS aware of it.
# mkdir -p
esp
/EFI/arch-limine
# cp /usr/share/limine/BOOTX64.EFI
esp
/EFI/arch-limine/
Tip
If installing to removable media,
or on certain motherboards onto which
efibootmgr
-created custom firmware boot entries do not work or are ignored
, it is recommended to copy the
BOOTX64.EFI
file to
esp
/EFI/BOOT/BOOTX64.EFI
instead, which is the default boot loader application search location, and to skip the rest of this section.
Limine does not add an entry for the boot loader in the NVRAM automatically. Use
efibootmgr
to setup an entry for Limine.
To do so, one can do the following:
# efibootmgr \
      --create \
      --disk /dev/sdX \
      --part Y \
      --label "Arch Linux Limine Boot Loader" \
      --loader '\EFI\arch-limine\BOOTX64.EFI' \
      --unicode
/dev/sdX
is the
disk
(
not a partition
) where the ESP is located on. For example
/dev/sda
or
/dev/nvme0n1
. See
Device file#Block device names
for a description of the block device naming scheme.
Y
is the partition index of the ESP, so if the ESP is
/dev/sda1
, then
Y
should be
1
.
Note
Read
efibootmgr
and its documentation for further information on how to add, remove, change, and sort boot entries.
BIOS systems with MBR
Deploying Limine on BIOS systems involves copying the
/usr/share/limine/limine-bios.sys
file, which contains stage 3 code that Limine needs to boot, to either the root, a
/boot
, a
/limine
, or a
/boot/limine
directory of any partition on the disk onto which Limine will be deployed, as long as the filesystem is supported. This usually means having to use a FAT partition for
/boot
, and copying the
limine-bios.sys
file to
/boot/limine
.
For example:
# mkdir -p /boot/limine
# cp /usr/share/limine/limine-bios.sys /boot/limine/
Then, early stage boot loader code needs to be deployed to the disk:
# limine bios-install /dev/sdX
/dev/sdX
is the
disk
(
not a partition
) where Limine is to be installed. For example
/dev/sda
or
/dev/nvme0n1
. This has to be the disk hosting the
/boot
partition. See
Device file#Block device names
for a description of the block device naming scheme.
BIOS systems with GPT
To deploy Limine for BIOS booting from a GPT partitioned disk, one needs to specify a GPT partition onto which to store the early stage boot loader code (this is in addition to the FAT boot partition, usually mounted at
/boot
, as explained in previous section). This partition must be at least 32 KiB in size, and should not be formatted with a file system or mounted.
Create a partition on the disk with no file system and with partition type GUID
21686148-6449-6E6F-744E-656564454649
:
fdisk
: create a partition and use the
t
command to
change its partition type
to
BIOS boot
.
gdisk
: create a partition with partition type
ef02
.
GNU Parted
: create a partition and set the
bios_grub
flag on it.
Then deploy the early stage boot loader code to the disk and partition:
# limine bios-install /dev/sd
X
partition_number
/dev/sdX
is the
disk
(
not a partition
) where Limine is to be installed. For example
/dev/sda
or
/dev/nvme0n1
. This has to be the disk hosting the
/boot
partition. See
Device file#Block device names
for a description of the block device naming scheme.
If the partition number is left out,
limine bios-install
will try to detect it automatically.
Like for the BIOS/MBR case, one must copy the
limine-bios.sys
file to either the root, a
/boot
, a
/limine
, or a
/boot/limine
directory in any of the partitions, using a supported file system, on the same disk where the early stage boot loader code was deployed.
UEFI + BIOS bootable drives
As long as a drive is
MBR
formatted, and it contains an EFI system partition (which can be the same as the
/boot
partition used for BIOS systems), it is possible to follow both the BIOS and UEFI deployment procedures in order to create a drive capable of booting on both legacy BIOS as well as UEFI systems. This is useful, for example, for installing an operating system on a USB flash drive which is to be used on multiple systems which may or may not support UEFI, or to ease moving hard drives across systems.
Configuration
limine
does not ship a default configuration file, it is therefore necessary to create one. This file is necessary to teach Limine which operating systems are available for boot. The configuration file has a lot of options as Limine allows for a fair degree of customisation. A detailed documentation of the configuration file, its format, and its options can be found
here
.
For UEFI systems, the configuration file may reside in the same directory as the Limine EFI executable, where it is first searched (recommended, as it allows installing multiple instances of Limine with different configurations, without conflicts).
For BIOS systems (or for UEFI systems where the configuration file was not placed alongside the Limine executable), the configuration file needs to reside on either the root, a
/boot
, a
/limine
, or a
/boot/limine
directory of a partition on the drive on which Limine is deployed, as long as the file system of said partition is supported.
The configuration file has to be named
limine.conf
.
Note
In the Limine configuration file,
boot():/
represents the partition onto which
limine.conf
is located.
Here follows a simple configuration file example that contains 1 boot menu entry that describes a typical Arch Linux kernel and initramfs:
limine.conf
timeout: 5

/Arch Linux
    protocol: linux
    path: boot():/vmlinuz-linux
    cmdline: root=UUID=
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
rw
    module_path: boot():/initramfs-linux.img
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
is the root file system's
UUID
.
In case the
/boot
partition, where the kernel and initramfs are, and the partition of the
limine.conf
file do not match (such as, for example, on UEFI systems with an extra
/boot
partition which is not the same as the ESP, and
limine.conf
is placed on the ESP), it may be necessary to replace
boot():/
in the configuration file with
uuid(
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
):/
, where
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
represents the
PARTUUID
of the
/boot
FAT partition.
Note
When adding a boot entry located on a different disk, Limine may fail with the error
Failed to open image with path: ... is the path correct?
On some systems, this can occur because the firmware does not initialize all storage devices during boot when fast boot is enabled. Some firmware implementations provide an option to force initialization of all disks, which may resolve the issue. Otherwise, disabling fast boot may be required.
Tip
If you are booting from a UEFI system with
Secure Boot
enabled, then consider securing both Limine configuration file and resource files like kernels and modules. Indeed, everyone that can access the FAT partition that stores the configuration file and the needed resources can alter these files, even with Secure Boot.
To prevent this, one can first embed the BLAKE2B (
b2sum
) checksum of every resource file in the configuration file. Limine file paths have an optional field containing the BLAKE2B checksum of the file. This field can be specified by appending the
#
character and then the
128 characters
checksum:
boot():/
path
#
checksum
Then, to protect the configuration file itself, one can embed its BLAKE2B checksum in the Limine EFI executable itself with the following command (where
checksum
represents the configuration file's own BLAKE2B checksum):
limine enroll-config
/path/to/deployed/limine.efi
checksum
The Limine EFI executable, now aware of the configuration file's BLAKE2B checksum, can be signed (see
sbctl(8)
) and securely loaded.
Memtest86+
Add one of the following entries to the configuration file.
For UEFI, install
memtest86+-efi
and add:
limine.conf
/Memtest86+
    protocol: efi
    path: boot():/memtest86+/memtest.efi
For BIOS, install
memtest86+
and add:
limine.conf
/Memtest86+
    protocol: linux
    path: boot():/memtest86+/memtest.bin
Windows entry (UEFI)
Add the following to the configuration:
limine.conf
/Windows
    protocol: efi
    path: boot():/EFI/Microsoft/Boot/bootmgfw.efi
Alternatively replace
boot():/
with
uuid(
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
):/
, where
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
is the
PARTUUID
of the ESP, if
limine.conf
is not on the ESP.
pacman hook
While not mandatory, it may be useful to set up a
pacman hook
to deploy Limine whenever it is upgraded.
UEFI
Note
Make sure to replace the ESP directory path if using something other than
esp
/EFI/arch-limine
(e.g.
esp
/EFI/BOOT
).
If using a 32-bit UEFI system, make sure to substitute
BOOTX64.EFI
with
BOOTIA32.EFI
.
/etc/pacman.d/hooks/99-limine.hook
[Trigger]
Operation = Install
Operation = Upgrade
Type = Package
Target = limine              

[Action]
Description = Deploying Limine after upgrade...
When = PostTransaction
Exec = /usr/bin/cp /usr/share/limine/BOOTX64.EFI
esp
/EFI/arch-limine/
BIOS
Note
Keep in mind that the device paths may change with the addition or removal of devices, moving the installation to different machines, and other factors. This may cause the BIOS hook to accidentally install Limine on an unwanted device.
/etc/pacman.d/hooks/99-limine.hook
[Trigger]
Operation = Install
Operation = Upgrade
Type = Package
Target = limine              

[Action]
Description = Deploying Limine after upgrade...
When = PostTransaction
Exec = /bin/sh -c "/usr/bin/limine bios-install
/dev/sdX
&& /usr/bin/cp /usr/share/limine/limine-bios.sys /boot/limine/"
/dev/sdX
is the
disk
(
not a partition
) where Limine was installed to in the previous steps.
Tips and tricks
Boot entry automation
To automate kernel integration (
initramfs
or
UKI
) with Limine, install:
limine-dracut-support
AUR
for
Dracut
or
limine-mkinitcpio-hook
AUR
for
mkinitcpio
Both tools include pacman hooks for automatically handling kernel entries.
Note
When updating or reinstalling Limine, its EFI image is automatically copied to the ESP on UEFI x86_64 system at
esp
/EFI/limine/limine_x64.efi
.
When using legacy BIOS or alternative CPU architectures such as ARM or RISC-V, automatic deployment of the EFI binary is disabled. In those cases, a specific Limine binary must be manually deployed to your boot partition.
Note
Some non-compliant UEFI motherboards (e.g., certain
MSI
boards) have non-standard or broken EFI implementations. They may not work with
efibootmgr
or kernel-based UEFI detection.
To skip UEFI detection and registration and set Limine as the fallback boot loader at the standard EFI path
esp
/EFI/BOOT/BOOTX64.EFI
, run:
# limine-install --skip-uefi --fallback
After that, open BIOS setup and change boot order to make the standard EFI path the default boot option.
Configurations
(Optional) Copy
/etc/limine-entry-tool.conf
to
/etc/default/limine
if not present.
Edit
/etc/default/limine
:
If
bootctl --print-esp-path
does not detect your ESP, manually set
ESP_PATH
to any mounted FAT32 boot partition you want to use. Then run
limine-install
to install the Limine EFI binary.
Configure permanent
kernel parameters
as described below.
Tip
If you want to use the same
kernel command line
for all installed kernels, the
recommended and default location
is
/etc/kernel/cmdline
. This file is supported by most initramfs tools and systemd.
If unsure about which kernel parameters to use, copy them from
/proc/cmdline
,
but do not do this from a live ISO, temporary environment, or snapshot.
Optionally, if
KERNEL_CMDLINE[default]
is set, it takes precedence over
/etc/kernel/cmdline
and
/proc/cmdline
.
Optionally,
KERNEL_CMDLINE[fallback]=
applies to kernel entries containing the name
fallback
.
Additionally,
KERNEL_CMDLINE[
kernel name
]=
corresponds to kernel entry name in the boot menu, allowing unique
kernel command line
per kernel entry. For example,
KERNEL_CMDLINE[linux-lts]=
for
linux-lts
kernel entry.
KERNEL_CMDLINE[
key
]+=
appends kernel parameters to the existing
KERNEL_CMDLINE[
key
]
values defined in drop-in config files under
/etc/limine-entry-tool.d/*.conf
. In contrast,
KERNEL_CMDLINE[
key
]=
fully replaces them according to config priority.
Support for multiple
initrd=
parameters parsed from kernel cmdline and converted into Limine module paths for non-UKI entries.
No quotes are needed at the start or end of cmdlines, since quotes inside are not escaped.
Note:
/etc/default/limine
has the highest priority and overrides all drop-in configs. Therefore, using
+=
is recommended when appending kernel parameters.
Example:
KERNEL_CMDLINE[default]+=rw root=UUID=...
KERNEL_CMDLINE[default]+=quiet splash initrd=/amd-ucode.img
(Optional) To save ESP space, set
DRACUT_FALLBACK
to
no
to disable automatic fallback generation by Dracut for
initramfs
or
UKI
.
(Optional) If you prefer booting with
UKI
, set
ENABLE_UKI
to
yes
.
Tip
Advantages of UKI:
systemd-boot
or
rEFInd
can automatically load UKIs generated by the tool.
If
sbctl
is installed and enabled, the tool can automatically sign the UKI with your Secure Boot key when updating or installing kernel.
(Optional) Set
FIND_BOOTLOADERS
to
yes
to detect and add systemd-boot, rEFInd, or the default EFI loader to Limine if they are present in the same ESP.
(Optional) Install
kernel-modules-hook
to keep the kernel in case of an upgrade failure, ensuring system functionality after reboot.
(Optional) Install Limine as the default EFI fallback. Some motherboards will automatically boot this if custom boot entries are removed by BIOS firmware or Windows updates.
# limine-install --fallback
(Optional)
Test
a different custom Limine binary, edit
/etc/default/limine
and add:
SKIP_LIMINE_VERSION_CHECK=yes
LIMINE_BINARY_PATH=
/path/to/custom_limine.efi
This skips the version validation and uses your specified Limine binary for installation to the boot partition.
Note
After making changes, run
limine-update
to regenerate
limine.conf
.
For more configuration options, refer to
limine-entry-tool README
Commands
limine-install
installs Limine to your EFI system partition.
limine-update
updates Limine and generates an initramfs or UKI depending on your initramfs generator:
For mkinitcpio: run
limine-mkinitcpio
instead of
mkinitcpio
For dracut: run
limine-dracut
instead of
dracut
limine-scan
detects active EFI boot entries (dual boot) and allows you to easily add them to Limine.
limine-list
displays boot entries in a hierarchical tree view with a default depth of 3.
Removes one or more matching boot entries by path, preserving their bootable files.
position
selects which of the matching entries is targeted. The default is 1. If set to 0, all matches are removed.
# limine-remove-entry "
entry name/sub-entry name/...
"
position
limine-enroll-config
uses
sbctl
to sign the binary
esp
/EFI/limine/limine_x64.efi
when Secure Boot is enabled.
Note
When
ENABLE_ENROLL_LIMINE_CONFIG=yes
is set in
/etc/default/limine
,
limine-enroll-config
will enroll a checksum of
esp
/limine.conf
into
esp/EFI/limine/limine_x64.efi
before signing it, to protect against unauthorized modifications.
Warning
Enabling this will
prevent
booting if you modify
limine.conf
and forget to re-enroll it afterward, due to Limine security restrictions. Disabling Secure Boot does not help in this case.
Make sure you have a reliable fallback boot loader
(without signing and enrollment)
for recovery before enabling this.
Hooks
Hooks are located in the following directories:
/etc/boot/hooks/
pre
.d/*
executed
before
kernel management and updating
esp
/limine.conf
on the boot partition.
/etc/boot/hooks/
post
.d/*
executed
after
kernel management and updating
esp
/limine.conf
on the boot partition.
Execution order is lexical based on filename sorting.
A hook can be disabled by appending the suffix
.disabled
to its filename.
Examples:
1.
/etc/boot/hooks/post.d/90-limine-enroll-config
enrolls a Limine config checksum into the Limine binary.
2.
/etc/boot/hooks/post.d/91-example-esp-set-ro.disabled
sets the boot partition to read-only to prevent accidental recursive writes. It is disabled by default.
See more information about
hooks
Tip
Managing kernels manually with limine-entry-tool
If you do not use an initramfs tool or use a different one like
booster
,
limine-entry-tool
AUR
does not provide initramfs generation and does not include automatic
pacman hooks
for kernel management.
You are free to create custom scripts using the
limine-entry-tool
command with your desired options to manage (add, update, and remove) boot entries.
Snapper snapshot integration for Btrfs
limine-snapper-sync
AUR
tool provides integration between
Snapper
and the Limine boot loader. It is useful for:
Booting into selected
Snapper
snapshot.
Providing 3 different methods for restoring a system snapshot:
rsync
,
replace
or native
snapper
.
Adding a "backup" snapshot entry to the Limine bootloader after restoring a snapshot, making it easy to revert if needed.
Automatically repairing corrupted bootable files on the boot partition by copying them from a newly created snapshot containing the same bootable files.
Automatically notifying the desktop about potential hardware issues if two independently generated hashes of a bootable file do not match.
Supporting an A/B-like system via multiple independent root subvolumes, each with its own Limine snapshot entries, requiring a unique machine-ID and a custom subvolume path in the kernel command line for booting.
Testing read-only snapshots: Use
overlayfs
to test any installed packages on an immutable-like system without modifying the original data. Note that this does not mean testing the boot partition or a separate home subvolume/partition.
Tip
Enable OverlayFS
For
dracut
, the
btrfs-snapshot-overlay
module works out of the box when using
limine-dracut-support
AUR
.
For
mkinitcpio
, manually add the
btrfs-overlayfs
or
sd-btrfs-overlayfs
hook
after the
filesystems
hook. Both are provided by
limine-mkinitcpio-hook
AUR
.
When using the
systemd hooks
, use
sd-btrfs-overlayfs
, as
btrfs-overlayfs
is incompatible.
Alternatively, when using
systemd init
, edit:
/etc/default/limine
SNAPSHOT_KERNEL_PARAMETERS+=systemd.volatile=overlay
When doing so, manually exclude the
btrfs-snapshot-overlay
module for
dracut
, or manually add
sd-volatile
after the
systemd
hook for
mkinitcpio
, then rebuild the initramfs.
Note
If you are using GNOME, be aware that
GDM
requires write access and cannot start from a read-only snapshot. You need an OverlayFS solution to provide a temporary writable layer.
The directory path
/usr/lib/modules/*
must be in the same root subvolume as
/
, because a selected snapshot requires its matching kernel modules from this path during boot. Otherwise, the snapshot will fail to boot.
Configurations
Note
It is recommended to have an
ESP
size of more than
4 GiB
, depending on how many bootable snapshots, kernel versions, and large early-boot modules (e.g., NVIDIA or Wi‑Fi drivers) you plan to install.
Tip
Automatic boot configuration
Use
limine-dracut-support
or
limine-mkinitcpio-hook
(see
#Boot entry automation
)  to automatically update kernel boot entries in
esp
/limine.conf
whenever kernels are installed, updated, or removed. This allows you to skip the first configuration step below.
1. Configure
esp
/limine.conf
to include either the
//Snapshots
or
/Snapshots
keyword for auto-generated snapshot entries.
An example:
limine.conf
/+Arch Linux
comment: Any comment
comment: machine-id=
yyyyyyyyyyyyyyyyyy
//Linux
    protocol: linux
    path: boot():/vmlinuz-linux
    cmdline: root=UUID=
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
rw rootflags=subvol=/@
    module_path: boot():/initramfs-linux.img

    //Snapshots
Note
Including the machine-ID from
/etc/machine-id
is optional but very helpful for automatic identification. Renaming OS names does not matter.
Bootable files must be placed in the same ESP as limine.conf, as only the
boot():
function is supported.
2. (Optional) Copy any configurations from
/etc/limine-snapper-sync.conf
to
/etc/default/limine
if they are not already present.
Edit
/etc/default/limine
, which will override
/etc/limine-snapper-sync.conf
:
If
bootctl --print-esp-path
does not detect your ESP, manually set
ESP_PATH
to your
ESP
/boot mount point.
(Optional) Set
LIMIT_USAGE_PERCENT
to stop creating new snapshot entries when the limit of the boot partition usage is exceeded. The default is
85
.
(Optional) Set
MAX_SNAPSHOT_ENTRIES
to limit the number of snapshot boot entries. The default is
8
, or change it to
auto
. In
auto
mode, older snapshot boot entries are automatically removed when the boot partition usage limit
MAX_SNAPSHOT_ENTRIES
is reached, without warning.
If using
custom
Snapper layout, make sure to configure the following:
Specify
ROOT_SUBVOLUME_PATH
for the path to your root subvolume. The default is
/@
in most cases.
Specify
ROOT_SNAPSHOTS_PATH
for the path to your root snapshots. The default is
/@/.snapshots
, which is the standard Snapper layout for the root subvolume
/@
.
3. Run the command to check if it succeeds or shows an error message:
# limine-snapper-sync
4. If everything works, then
enable/start
limine-snapper-sync.service
to automatically synchronize boot entries with the Snapper snapshot list.
5. (Optional) Install
snap-pac
. It triggers Snapper to create snapshots during system updates, which limine-snapper-sync then synchronizes to generate related snapshot entries in Limine.
For further details and additional configuration options, refer to
limine-snapper-sync README
.
Commands
limine-snapper-sync
synchronizes Limine snapshot entries with the Snapper list.
limine-snapper-list
displays the current Limine snapshot entries.
limine-snapper-info
provides detailed information about versions, the total number of bootable snapshots, and verifies bootable files.
limine-snapper-restore
restores your system, including matching kernel versions, from a selected bootable snapshot.
limine-snapper-remove
number1
..
number2
removes snapshot boot entries to free up space on the boot partition. It does not  delete the corresponding Snapper snapshots.
Known issues
Supports only any Snapper layouts, not arbitrary Btrfs layouts without Snapper.
Cannot generate bootable snapshot entries for old snapshots created before the tool was installed, as these snapshots typically no longer have their corresponding kernel versions.
Troubleshooting
Having problems? Check out the
troubleshooting guide in the README
See also
Limine's GitHub repository