mkosi

mkosi stands for Make Operating System Image, and is a tool for easily building customized OS images. It's a fancy Python wrapper around dnf, apt, pacman and zypper that may generate disk images with a number of bells and whistles.

It has nifty features like:

no_new_privileges to build images as an unpriviliged user
An Overlay filesystem to re-use existing distribution package caches reducing disk space requirements
Deep Freedesktop.org and systemd integration
Wide range of output formats like Raw GPT disk image, plain directory, tar, cpio and USI / UKI.

The project is actively maintained and includes extensive documentation for customizing images across various distributions. The arch-boxes project uses mkosi to build various virtual-machine images for its fortnightly release.

On Arch Linux, mkosi can be used to build bootable Unified Kernel Images (UKI), including those signed for Secure Boot. Creating images with encrypted LUKS volumes is as straightforward as defining Passphrase= in mkosi.conf. Package lists can be defined directly in the mkosi.default file under the Packages= section, and additional files or configuration can be added using overlay directories such as mkosi.extra/.

mkosi has a strong focus on developer workflows such as testing, debugging, and producing minimal, production-ready images. A common use case involves adding a mkosi.default configuration file to a project (e.g. written in C or Python), which then allows automated image generation tailored to the project’s needs.

During the build process, mkosi can create a temporary development image that includes headers and tooling, compile the project within it, run tests, and then discard this image. It subsequently builds a second image without development dependencies, containing only the resulting build artifacts and any other explicitly configured packages.

This resulting image is minimal, self-contained, and suitable for deployment via tools such as RAUC, or OSTree, making it well-suited for automated provisioning of servers, embedded systems, or IoT targets.

Note: It is highly recommended to run mkosi on a File system that supports reflinks such as XFS and Btrfs and to keep all related directories on the same file system. This allows mkosi to create images very quickly by using reflinks to perform copying via copy-on-write operations.

Installation

Install mkosi or mkosi-git^AUR. Depending on what distribution you want to use in your OS tree/image, install the following packages:

Distribution	Package
Arch	arch-install-scripts
Debian	debootstrap, debian-archive-keyring, apt
Ubuntu	debootstrap, ubuntu-keyring, apt
Fedora	dnf
OpenSUSE	zypper
CentOS	dnf-legacy-utils^AUR

Basic usage

You can create an image by just running it without any arguments:

$ mkosi

You can specify option as arguments or by editing files in the current folder.

Create and boot a Debian image

The following example will create a bootable image with the latest Debian version and packages openssh-client and vim installed. This command requires mkosi's optional dependencies mtools and systemd-ukify. Depending on the image, can also be built by an unprivileged (non-root) user:

$ mkosi --distribution debian --release bookworm --format disk --checksum --root-password password --include mkosi-vm --package openssh-client,vim --repository-key-fetch=yes --output image.raw

systemd-nspawn can boot the resulting image:

# systemd-nspawn --boot --image image.raw

It can also be virtualized with QEMU/KVM or with systemd-vmspawn(1):

$ mkosi --output image.raw --qemu-smp 2 qemu

You can also write this image to a USB drive and use it to boot your computer.

Using configuration files

The same Debian image can be created using a configuration file, mkosi.conf, and then run mkosi without any arguments:

mkosi.conf

[Distribution]
Distribution=debian
Release=bookworm
RepositoryKeyFetch=true

[Output]
Format=disk
Output=image.raw

[Include]
Include=mkosi-vm

[Content]
Bootable=yes
Packages=openssh-client
         vim
RootPassword=password

[Validation]
Checksum=yes

The built-in mkosi-vm profile adds the necessary packages in order to run a system and is maintained by the mkosi maintainers.

Downloaded package files and temporary build files are stored in the home cache directory or in /var/cache/mkosi and /var/tmp.

Configuration settings

Settings can be specified as command-line arguments or, for example, in a file called mkosi.conf in the current directory. The most important settings are:

Command line	Configuration file	Description
`--distribution`	[Distribution] Distribution=	Name of the distribution to install. Supported are: `fedora, debian, ubuntu, arch, opensuse, mageia, centos, openmandriva, rocky, alma`
`--release`	[Distribution] Release=	Version of the distribution: a numeric string or a distribution version name (`bookworm, …`)
`--format`	[Output] Format=	Format of the image to create. For example: directory: plain directory disk: image file with GPT partition table tar: tarball of a plain directory
`--output`	[Output] Output=	Name of the image file or directory
`--output-directory`	[Output] OutputDirectory=	Location of the image file or directory (and other generated artifacts)
`--bootable`	[Content] Bootable=	Enable or disable generation of a bootable image: `yes, no`
`--package`	[Content] Packages=	List of packages to be installed into the image: (multi) line and/or comma separated list
`--root-password`	[Content] RootPassword=	Initial root password

Usage as initramfs generator

Mkosi provides a kernel-install plugin to build an initramfs, similarly to mkinitcpio or dracut.

In order to use it, install cpio and edit the kernel-install configuration file:

/etc/kernel/install.conf

initrd_generator=mkosi-initrd

Note: The generated initrds are much larger than the ones generated by mkinitcpio.