mkosi

Related articles
systemd
systemd-nspawn
Linux Containers
Docker
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 provides
mkosi(1)
for customizing images across various distributions.
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
. 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 trixie --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=trixie
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 (
trixie, …
)
--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 initramfs are much larger than the ones generated by mkinitcpio. The initramfs size can be significantly reduced by configuring zstd compression via the
CompressLevel=
Output option.
See also
Mkosi on Github
Longer introduction by Poettering, one of its developers
A re-introduction to mkosi by Daan De Meyer, the current maintainer
Building Arch Linux USIs with mkosi
Creating Arch Linux rescue image with Secure Boot
Jelle's video presentation at All Systems Go on creating Arch Linux images using mkosi