Jump to content

# Limine

From ArchWiki

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/sdX 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-supportAUR for Dracut

or

- limine-mkinitcpio-hookAUR for mkinitcpio

Both tools include pacman hooks for automatically handling kernel entries.

Note

- When updating or reinstalling Limine, its EFI image is automatically deployed to the ESP on UEFI system with x86_64 architecture.
- 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.
- (Optional) Set `KERNEL_CMDLINE[default]+=` with your preferred complete kernel parameters.

Tip

- If unsure about which kernel parameters to use, copy them from `/proc/cmdline` into `KERNEL_CMDLINE[default]=`, but do not do this from a live ISO, temporary environment, or snapshot.
- If `KERNEL_CMDLINE[default]=` or `KERNEL_CMDLINE=` is not set, the tool will first try to read from the file `/etc/kernel/cmdline`. If unavailable, it will fall back to reading from `/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 cmdline/parameters 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.

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"

- (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) Set `ENABLE_LIMINE_FALLBACK` to `yes` to make the Limine EFI entry the default fallback. Some motherboards will automatically boot this if custom boot entries get wiped by firmware updates.
- (Optional) Install kernel-modules-hook to keep the kernel in case of an upgrade failure, ensuring system functionality after reboot.

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-install --fallback` installs Limine as the default fallback boot loader.

- `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.

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-toolAUR 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-syncAUR 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 from old snapshots on the ESP when a new snapshot with the same bootable files is created.
- Automatically logging error messages about potential hardware issues if two hashes of the same bootable file do not match on the ESP.
- 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-supportAUR.

For mkinitcpio, manually add the `btrfs-overlayfs` or `sd-btrfs-overlayfs` hook after the `filesystems` hook. Both are provided by limine-mkinitcpio-hookAUR.
When using the systemd hooks, use `sd-btrfs-overlayfs`, as `btrfs-overlayfs` is incompatible.

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 `MAX_SNAPSHOT_ENTRIES` to limit the number of snapshot entries. The default is 8.
- (Optional) Set `LIMIT_USAGE_PERCENT` to stop creating new snapshot entries when the limit of ESP usage is exceeded. The default is 85.

- 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

Note If it shows an error that command `limine-reset-enroll` and `limine-enroll-config` not found, these commands are provided by either limine-dracut-supportAUR, limine-mkinitcpio-hookAUR or limine-entry-toolAUR, which is not installed.

This error can be safely ignored if you do not use them. Alternatively, to prevent this error, edit `/etc/limine-snapper-sync.conf` to remove two lines:

    COMMANDS_BEFORE_SAVE="limine-reset-enroll"
    COMMANDS_AFTER_SAVE="limine-enroll-config"

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.

#### 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 Codeberg repository

Category:

- Boot loaders

Limine
Add topic