Omarchy Boot System Components: mkinitcpio, Limine, and Plymouth Explained

The Omarchy boot system integrates mkinitcpio for initramfs generation, Limine as the UEFI bootloader, and Plymouth for graphical boot splash, orchestrated through custom hooks and wrapper scripts that ensure synchronized updates across all three components.

The omacom/omarchy repository defines a cohesive boot architecture for Arch-based systems, combining three distinct technologies into a unified startup flow. Understanding how mkinitcpio, Limine, and Plymouth interact within this framework is essential for customizing boot behavior, troubleshooting startup issues, or modifying the boot splash theme.

mkinitcpio Initramfs Generation with Custom Hooks

Omarchy extends the standard mkinitcpio configuration through modular drop-in files located in etc/mkinitcpio.conf.d/. These configurations determine which modules, binaries, and hooks are included in the initial ramdisk.

Omarchy-Specific Hook Configuration

The primary configuration file etc/mkinitcpio.conf.d/omarchy_hooks.conf appends critical hooks to the initramfs build process:

• plymouth: Embeds the splash screen assets into the initramfs so the graphical boot animation starts immediately upon kernel load.
• omarchy_resume: Enables hibernation resume support specific to Omarchy's system layout.

For hardware-specific requirements, the repository includes etc/mkinitcpio.conf.d/thunderbolt_module.conf, which ensures Thunderbolt modules are available in the early boot environment.

UKI Generation via limine-mkinitcpio

Rather than calling mkinitcpio directly, Omarchy uses the limine-mkinitcpio helper. This script performs two critical operations:

1. Regenerates the Unified Kernel Image (UKI) for the Limine bootloader.
2. Executes mkinitcpio -P to rebuild initramfs images for all installed kernels, ensuring the Plymouth assets and Omarchy hooks are synchronized.

# Regenerate initramfs and UKI after modifying hooks

sudo limine-mkinitcpio

Limine Bootloader Configuration

Limine serves as the UEFI bootloader in the Omarchy stack, responsible for loading the UKI and presenting the boot menu. Configuration is managed through a combination of static templates and entry-tool drop-ins.

Configuration File Layout

Omarchy maintains Limine configuration templates in the default/limine/ directory:

• default/limine/limine.conf: The primary bootloader configuration defining menu behavior, timeouts, and UI settings.
• default/limine/default.conf: Contains default boot entry parameters passed to the kernel.

These templates are deployed to the system via the omarchy-refresh-limine script, which copies files into /etc/limine/ and ensures the bootloader remains synchronized with Omarchy defaults.

Entry Tool Integration

Boot entries are dynamically managed through /etc/limine-entry-tool.d/omarchy-defaults.conf, which provides the entry-tool with default parameters for generating Limine menu items. This separation allows the system to update kernel entries automatically while preserving custom bootloader aesthetics.

Migration and Updates

The omarchy-upgrade-to-quattro script handles major version migrations by removing legacy Limine configuration files and invoking limine-mkinitcpio to regenerate the UKI with current settings.

# Refresh Limine configuration after system updates

omarchy-refresh-limine

Plymouth Boot Splash Integration

Plymouth provides the graphical boot splash screen during the initramfs phase. Omarchy integrates Plymouth deeply into the build process, ensuring theme assets are embedded within the initramfs itself.

Theme Management Scripts

Omarchy includes specialized wrappers for theme customization:

• bin/omarchy-plymouth-set: Validates color inputs and logo paths, writes the theme configuration, and triggers limine-mkinitcpio to rebuild the initramfs with new assets.
• bin/omarchy-plymouth-reset: Removes custom theme configurations and reverts to the default Omarchy Plymouth theme located in default/plymouth/.

The omarchy-refresh-plymouth script synchronizes the system's Plymouth configuration with the templates stored in default/plymouth/.

Custom Theme Application

To apply a custom boot splash with specific background color, text color, and logo:

# Apply custom colors and logo

omarchy-plymouth-set "#1d2021" "#ebdbb2" /path/to/custom-logo.png

This command updates the Plymouth configuration and immediately rebuilds the initramfs via limine-mkinitcpio, ensuring the splash screen appears on the next boot.

Summary

• mkinitcpio builds the initramfs using Omarchy-specific hooks (omarchy_hooks.conf) that include Plymouth support and resume functionality, triggered via limine-mkinitcpio for UKI generation.
• Limine loads the resulting UKI and presents the boot menu, configured through templates in default/limine/ and entry definitions in /etc/limine-entry-tool.d/, managed by omarchy-refresh-limine.
• Plymouth renders the graphical boot splash with assets stored in default/plymouth/, applied through omarchy-plymouth-set and baked into the initramfs during the build process.
• Integration scripts (limine-mkinitcpio, omarchy-upgrade-to-quattro, omarchy-refresh-plymouth) ensure the three components remain synchronized during system updates and configuration changes.

Frequently Asked Questions

How does Omarchy ensure the Plymouth theme appears immediately during boot?

Omarchy embeds Plymouth assets directly into the initramfs through the mkinitcpio plymouth hook defined in etc/mkinitcpio.conf.d/omarchy_hooks.conf. When you run omarchy-plymouth-set or limine-mkinitcpio, the script rebuilds the initramfs with the theme files included, allowing the splash screen to display as soon as the kernel loads the initial ramdisk, before the root filesystem is mounted.

What is the purpose of the limine-mkinitcpio command in Omarchy?

limine-mkinitcpio is a wrapper that bridges the bootloader and initramfs generation. According to the Omarchy source, it creates the Unified Kernel Image (UKI) required by Limine and then executes mkinitcpio -P to rebuild all initramfs images. This ensures that any changes to mkinitcpio hooks, Plymouth themes, or kernel parameters are atomically synchronized with the bootloader's UKI.

Where are the Limine bootloader configuration templates stored in the Omarchy repository?

The default Limine configuration templates reside in default/limine/, specifically limine.conf for the main bootloader settings and default.conf for entry parameters. The omarchy-refresh-limine script copies these files to /etc/limine/ during system updates, while omarchy-upgrade-to-quattro removes outdated Limine configurations when migrating to newer Omarchy versions.

Can I use standard mkinitcpio commands instead of limine-mkinitcpio in Omarchy?

While standard mkinitcpio commands will rebuild the initramfs, they will not regenerate the Unified Kernel Image (UKI) that Limine requires. Using limine-mkinitcpio is necessary to ensure the UKI reflects the latest initramfs and kernel parameters. Running mkinitcpio -P alone may leave the bootloader pointing to an outdated UKI, causing boot failures or missing splash screens.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}