mkinitcpio

Perform a dry run (print what would be done without actually doing it)

$ mkinitcpio

$ sudo mkinitcpio [[-P|--allpresets]]

$ sudo mkinitcpio [[-p|--preset]] linux

$ sudo mkinitcpio [[-p|--preset]] linux-lts

$ sudo mkinitcpio [[-c|--config]] [path/to/mkinitcpio.conf] [[-g|--generate]] [path/to/initramfs.img]

$ sudo mkinitcpio [[-k|--kernel]] [kernel_version] [[-g|--generate]] [path/to/initramfs.img]

$ mkinitcpio [[-L|--listhooks]]

$ mkinitcpio [[-H|--hookhelp]] [hook_name]

mkinitcpio [-p | -P | -U | -u] []
mkinitcpio -g []
mkinitcpio -L [-c ]
mkinitcpio -h | -V

-p , --preset
    Processes the specified preset file from /etc/mkinitcpio.d/, generating an image based on its configuration.

-P, --allpresets
    Processes all preset files found in /etc/mkinitcpio.d/, regenerating all associated images. This is commonly used after kernel updates.

-g , --generate
    Generates a single initramfs image directly using the current configuration (or specified via -c).

-U, --update-all
    Updates all images specified by all presets. Similar to -P but specifically for updating existing images.

-u, --update
    Updates kernel images matching the current running kernel's version (uname -r).

-c , --config
    Specifies an alternative configuration file to use instead of the default /etc/mkinitcpio.conf.

-r , --kernel
    Specifies the kernel release version for which to generate the image (e.g., 4.19.0-arch1-1-ARCH).

-z , --compress
    Specifies the compression method to use for the initramfs image (e.g., gzip, lz4, zstd).

-L, --list-hooks
    Lists all available hooks that mkinitcpio can use, along with their brief descriptions.

-t, --test
    Performs a dry run, parsing the configuration and hooks but not actually generating an image. Useful for debugging configuration issues.

-v, --verbose
    Provides more detailed output during the image generation process.

-d, --debug
    Provides even more detailed, debug-level output.

-h, --help
    Displays a help message with command usage and options.

-V, --version
    Displays the version information of mkinitcpio.

mkinitcpio is a powerful script used primarily in Arch Linux and its derivatives to generate a customized initial RAM disk (initramfs) image. This image is loaded by the kernel during the early boot process, providing essential modules and utilities required to mount the real root filesystem.

The initramfs is crucial for systems that rely on complex storage setups, such as LVM (Logical Volume Management), software RAID, encrypted root filesystems (e.g., LUKS), or certain advanced filesystem types like Btrfs or ZFS. It ensures that the necessary drivers and tools are available before the actual root filesystem is accessible.

mkinitcpio operates based on a configuration file (typically /etc/mkinitcpio.conf) and a system of "hooks." These hooks are scripts that define which modules, binaries, and configurations should be included in the initramfs. By selectively including only what's needed, mkinitcpio helps keep the initramfs image size optimized while ensuring system bootability. It's often run automatically after kernel updates or manually when boot-critical configurations change.

Incorrect configuration in /etc/mkinitcpio.conf or missing hooks can lead to an unbootable system. Always test changes in a safe environment or have a recovery plan.
Regeneration is essential after kernel upgrades or changes to critical components like LVM, software RAID, or root filesystem encryption.
While the principles are universal, mkinitcpio is primarily developed and maintained for Arch Linux, and its default configuration and hook ecosystem are tailored to Arch's system.

Hooks are shell scripts located in /usr/lib/initcpio/hooks/ and configured in /etc/mkinitcpio.conf. Each hook adds specific functionality to the initramfs, such as:
base: Essential utilities for the initramfs environment.
udev: Populates /dev and loads modules.
autodetect: Attempts to detect and include necessary modules.
block: Adds modules for block devices.
keyboard: Includes keyboard layout and keymap functionality.
encrypt: Provides support for encrypted root filesystems (e.g., LUKS).
lvm2: Includes LVM tools to activate logical volumes.
filesystems: Adds modules for common filesystems (e.g., ext4, xfs, btrfs).
Hooks ensure that the initramfs contains precisely what's needed to find and mount the root filesystem.

Presets are configuration files found in /etc/mkinitcpio.d/ (e.g., linux.preset, linux-lts.preset). They simplify the generation process by defining a specific configuration for an initramfs image, including the kernel version, compression, and output path. Users typically don't run mkinitcpio directly with all options; instead, they use a preset (e.g., mkinitcpio -p linux) or let mkinitcpio -P process all presets. This makes kernel updates streamlined, as pacman often triggers mkinitcpio -P automatically.

mkinitcpio emerged as the default initramfs generator for Arch Linux, replacing older, less flexible methods. Its development focused on providing a highly customizable and robust solution for Arch's "rolling release" model and its users' diverse hardware and software configurations. It introduced the hook-based system, which allows users to easily add support for various features like LUKS encryption, LVM, different filesystems, and network boot, making it integral to the Arch ecosystem.

dracut(8), boot(7), kernel(7), init(8)