---
obj: concept
arch-wiki: https://wiki.archlinux.org/title/Mkinitcpio
rev: 2024-12-16
---

# mkinitcpio
The initial ramdisk is in essence a very small environment (early userspace) which loads various kernel modules and sets up necessary things before handing over control to `init`. This makes it possible to have, for example, encrypted root file systems and root file systems on a software [RAID](filesystems/RAID.md) array. _mkinitcpio_ allows for easy extension with custom hooks, has autodetection at runtime, and many other features.

## Configuration
The primary configuration file for _mkinitcpio_ is `/etc/mkinitcpio.conf`. Additionally, preset definitions are provided by kernel packages in the `/etc/mkinitcpio.d` directory (e.g. `/etc/mkinitcpio.d/linux.preset`).

- `MODULES` : Kernel modules to be loaded before any boot hooks are run.
- `BINARIES` : Additional binaries to be included in the initramfs image.
- `FILES` : Additional files to be included in the initramfs image.
- `HOOKS` : Hooks are scripts that execute in the initial ramdisk.
- `COMPRESSION` : Used to compress the initramfs image.

### MODULES
The `MODULES` array is used to specify modules to load before anything else is done.

Modules suffixed with a `?` will not throw errors if they are not found. This might be useful for custom kernels that compile in modules which are listed explicitly in a hook or configuration file.

### BINARIES and FILES
These options allow users to add files to the image. Both `BINARIES` and `FILES` are added before hooks are run, and may be used to override files used or provided by a hook. `BINARIES` are auto-located within a standard `PATH` and are dependency-parsed, meaning any required libraries will also be added. `FILES` are added _as-is_. For example:
```
FILES=(/etc/modprobe.d/modprobe.conf)

BINARIES=(kexec)
```
Note that as both `BINARIES` and `FILES` are Bash arrays, multiple entries can be added delimited with spaces.

### HOOKS
The `HOOKS` array is the most important setting in the file. Hooks are small scripts which describe what will be added to the image. For some hooks, they will also contain a runtime component which provides additional behavior, such as starting a daemon, or assembling a stacked block device. Hooks are referred to by their name, and executed in the order they exist in the `HOOKS` array of the configuration file.

The default `HOOKS` setting should be sufficient for most simple, single disk setups. For root devices which are stacked or multi-block devices such as [LVM](filesystems/LVM.md), [RAID](filesystems/RAID.md), or [dm-crypt](filesystems/LUKS.md), see the respective wiki pages for further necessary configuration.

#### Common Hooks
| Hook            | Feature                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **base**        | Sets up all initial directories and installs base utilities and libraries. Always keep this hook as the first hook unless you know what you are doing, as it provides critical busybox init when not using **[systemd](systemd/Systemd.md)** hook. Optional when using the **[systemd](systemd/Systemd.md)** hook as it only provides a busybox recovery shell.                                                                                                                                                                                                     |
| **udev**        | Adds udevd, udevadm, and a small subset of udev rules to your image.                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **usr**         | Adds support for /usr on a separate partition.                                                                                                                                                                                                                                                                                                                                                                                                                           |
| **resume**      | Tries to resume from the "suspend to disk" state.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| **btrfs**       | Sets the required modules to enable [Btrfs](filesystems/Btrfs.md) for using multiple devices with [Btrfs](filesystems/Btrfs.md). You need to have btrfs-progs installed to use this. This hook is not required for using [Btrfs](filesystems/Btrfs.md) on a single device.                                                                                                                                                                                                                                                                                                                      |
| **autodetect**  | Shrinks your initramfs to a smaller size by creating a whitelist of modules from a scan of sysfs. Be sure to verify included modules are correct and none are missing. This hook must be run before other subsystem hooks in order to take advantage of auto-detection. Any hooks placed before 'autodetect' will be installed in full.                                                                                                                                                                                 |
| **modconf**     | Includes modprobe configuration files from `/etc/modprobe.d/` and `/usr/lib/modprobe.d/`.                                                                                                                                                                                                                                                                                                                                                                                                                               |
| **block**       | Adds all block device modules, formerly separately provided by the _fw_, _mmc_, _pata_, _sata_, _scsi_, _usb_, and _virtio_ hooks.                                                                                                                                                                                                                                                                                                                                                                                      |
| **net**         | Adds the necessary modules for a network device.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| **dmraid**      | Provides support for fakeRAID root devices. You must have dmraid installed to use this. Note that it is preferred to use mdadm with the mdadm_udev hook with fakeRAID if your controller supports it.                                                                                                                                                                                                                                                                                                                   |
| **keyboard**    | Adds the necessary modules for keyboard devices. Use this if you have an USB or serial keyboard and need it in early userspace (either for entering encryption passphrases or for use in an interactive shell). As a side effect, modules for some non-keyboard input devices might be added too, but this should not be relied on. Supersedes old _usbinput_ hook.                                                                                                                                                     |
| **keymap**      | Adds the specified keymap(s) from `/etc/vconsole.conf` to the initramfs. If you use system encryption "[Dm-crypt](filesystems/LUKS.md)/Encrypting an entire system"), especially full-disk encryption, make sure you add it before the `encrypt` hook.                                                                                                                                                                                                                                                                                         |
| **encrypt**     | Adds the `dm_crypt` kernel module and the `cryptsetup` tool to the image.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| **lvm2**        | Adds the device mapper kernel module and the `lvm` tool to the image.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| **fsck**        | Adds the fsck binary and file system-specific helpers to allow running fsck against your root device (and `/usr` if separate) prior to mounting. If added after the **autodetect** hook, only the helper specific to your root file system will be added. Usage of this hook is **strongly** recommended, and it is required with a separate `/usr` partition. It is highly recommended that if you include this hook that you also include any necessary modules to ensure your keyboard will work in early userspace. |
| **filesystems** | This includes necessary file system modules into your image. This hook is **required** unless you specify your file system modules in `MODULES`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |

### UKI
A Unified Kernel Image (UKI) is a single executable file that can be directly booted by UEFI firmware or automatically sourced by boot-loaders.

In essence, a UKI combines all the necessary components for the operating system to start up, including: 
- EFI stub loader
- Kernel command line
- Microcode updates
- Initramfs image (initial RAM file system)
- Kernel image itself
- Splash screen

To enable the UKI edit `/etc/mkinitcpio.d/linux.preset`:

```sh
default_uki="/boot/EFI/Linux/arch-linux.efi"

fallback_uki="/boot/EFI/Linux/arch-linux-fallback.efi"
```

Build the Unified Kernel Image:

```sh
mkinitcpio --allpresets
```
