mkinitcpio and the boot path

arch / published / guide #43 / ≈ 4 min read

When an Arch (or Manjaro) machine boots, a small chain of programs runs before your kernel is fully on its feet. mkinitcpio builds the most mysterious link in that chain — a tiny temporary filesystem called the initramfs that the kernel uses as scaffolding while it's starting up. Most of the time you never think about it. The day you do, this guide will save you.

The boot path, in plain words

  1. Firmware (UEFI or BIOS) runs first and hands off to a bootloader.
  2. The bootloader (GRUB, systemd-boot, or rEFInd) loads the kernel image and an initramfs file from /boot.
  3. The kernel starts and looks at the initramfs.
  4. The initramfs contains just enough — kernel modules, tiny utilities — to find and mount your real root filesystem.
  5. Once the real root is mounted, the kernel switches to it and runs /sbin/init (usually systemd), and you're up.

That step 4 is the bit mkinitcpio builds. If it's wrong — say, it doesn't include the driver for your storage controller — the kernel can't find its own root filesystem and the boot fails with "ALERT! UUID=… does not exist."

The two files that matter

/etc/mkinitcpio.conf                      # the recipe
/boot/initramfs-linux.img                 # the built image

Open the recipe:

sudo nano /etc/mkinitcpio.conf

The two interesting lines are MODULES= and HOOKS=.

HOOKS — the assembly order

A typical Arch HOOKS line:

HOOKS=(base udev autodetect microcode modconf kms keyboard keymap consolefont block filesystems fsck)

Each word is a small bundle of scripts and drivers added to the initramfs in that order. Some of the important ones:

  • base, udev — the essentials; always present.
  • autodetect — clever: only includes modules for hardware currently in this machine. Smaller, faster image. Remove this and you get a generic-everything image (heavier but portable).
  • microcode — loads CPU bug patches before anything sensitive runs.
  • modconf — honours module config files under /etc/modprobe.d/.
  • kms — kernel mode-setting; gives you the right framebuffer resolution early.
  • keyboard, keymap — so you can type the LUKS passphrase before the real root is mounted.
  • encrypt — add this when using LUKS-encrypted root. Must be before filesystems.
  • lvm2 — for LVM-based root. Also before filesystems.
  • block — block-device drivers.
  • filesystems — the filesystem drivers themselves (ext4, btrfs, …).
  • fsck — run filesystem check at boot if needed.

The order matters. A LUKS-on-LVM setup looks like:

HOOKS=(base udev autodetect microcode modconf kms keyboard keymap consolefont block encrypt lvm2 filesystems fsck)

MODULES — explicit modules to include

Usually empty. If autodetect misses something — say, you're building an initramfs for a different machine, or you have an exotic storage controller — list it here:

MODULES=(virtio_pci virtio_blk virtio_net)

Rebuild after any change

sudo mkinitcpio -P

The -P means "all presets" — rebuild the image for every installed kernel. You'll see lines about each kernel ending in ==> Image generation successful.

To rebuild for just one kernel:

sudo mkinitcpio -p linux

When you actually need to touch mkinitcpio.conf

  • You set up LUKS / LVM / RAID / btrfs-as-root after install — add the right hook.
  • The kernel can't find your root — autodetect missed a module. Add it to MODULES.
  • You want a portable initramfs (for cloning to identical hardware) — remove autodetect.
  • You want a plymouth boot splash — add the plymouth hook.
  • You changed your keyboard layout for LUKS — set KEYMAP in /etc/vconsole.conf and rebuild.

How to test before rebooting

Use the -W flag to write to a temporary file you can inspect:

sudo mkinitcpio -P -W /tmp/initramfs-test
lsinitcpio /tmp/initramfs-test | grep -i encrypt          # is the encrypt hook included?

lsinitcpio peeks inside an initramfs without unpacking it — useful for "did my change land?"

The boot is broken — now what?

If the system drops you to an emergency shell at boot, the message at the top usually tells you why. Common causes:

  • "Cannot find root device UUID=…" — initramfs missed a storage driver. Boot from a live USB, chroot in, fix mkinitcpio.conf, rebuild.
  • LUKS password prompt never appears — the encrypt hook is missing or in the wrong order.
  • Kernel panic just after the bootloader — initramfs file is missing or corrupted. Boot the fallback kernel from the boot menu, then sudo mkinitcpio -P.

The chroot rescue routine

From an Arch live USB:

cryptsetup open /dev/sda3 cryptroot     # if LUKS
mount /dev/mapper/cryptroot /mnt        # or /dev/sda3 directly
mount /dev/sda1 /mnt/boot               # the EFI / boot partition
arch-chroot /mnt
mkinitcpio -P
exit
umount -R /mnt
reboot

That single sequence fixes the majority of "rebuilt initramfs and now it doesn't boot" situations.

The shortest summary

Most users edit /etc/mkinitcpio.conf exactly once — when they add LUKS or LVM — and then forget about it for years. If a kernel update boots fine, no action is needed; pacman runs mkinitcpio automatically. When something goes wrong, the chroot routine above and one extra hook will almost always fix it.

← back to index