A fancy wrapper around dnf --installroot, apt, pacman and zypper that generates customized disk images with a number of bells and whistles.

For a longer description and available features and options, see the man page or run mkosi documentation. When getting started see the EXAMPLES section.

You can install mkosi from your distribution using its package manager or install the development version from git. If you install mkosi using your distribution's package manager, make sure it installs at least mkosi v16 or newer (Use mkosi --version to check). If your distribution only packages an older version of mkosi, it is recommended to install mkosi using one of the alternative installation methods listed below instead.

To run mkosi straight from its git repository, you can invoke the shim bin/mkosi. The MKOSI_INTERPRETER environment variable can be set when using the bin/mkosi shim to configure the python interpreter used to execute mkosi. The shim can be symlinked to e.g. ~/.local/bin to make it accessible from the PATH. Note that to make this work you might have to add ~/.local/bin to your user's PATH.

git clone https://github.com/systemd/mkosi ln -s $PWD/mkosi/bin/mkosi ~/.local/bin/mkosi mkosi --version

mkosi also provides other companion tools that can be enabled in a similar manner.

ln -s $PWD/mkosi/bin/mkosi-addon ~/.local/bin/mkosi-addon ln -s $PWD/mkosi/bin/mkosi-initrd ~/.local/bin/mkosi-initrd ln -s $PWD/mkosi/bin/mkosi-sandbox ~/.local/bin/mkosi-sandbox

mkosi can also be installed straight from the git repository url using pipx:

pipx install git+https://github.com/systemd/mkosi.git mkosi --version

which will transparently install mkosi into a Python virtual environment and a mkosi binary to ~/.local/bin. This is, up to the path of the virtual environment and the mkosi binary, equivalent to

python3 -m venv mkosivenv mkosivenv/bin/pip install git+https://github.com/systemd/mkosi.git mkosivenv/bin/mkosi --version

You can also package mkosi as a zipapp that you can deploy anywhere in your PATH. Running this will leave a mkosi binary in builddir/

git clone https://github.com/systemd/mkosi cd mkosi tools/generate-zipapp.sh builddir/mkosi --version

Besides the mkosi binary, you can also call mkosi via

python3 -m mkosi

when not installed as a zipapp.

Please note, that the python module exists solely for the usage of the mkosi binary and is not to be considered a public API.

mkosi packages for Debian, Ubuntu, Fedora and SUSE are built from latest main and published as repositories for the respective distributions on OBS. Follow these instructions to enable the appropriate repository.

mkosi can also be used as a kernel-install plugin to build initrds and addons. It is recommended to use only one of these two plugins at a given time.

To enable this feature, install kernel-install/50-mkosi.install into /usr/lib/kernel/install.d. Extra distro configuration for the initrd can be configured in /usr/lib/mkosi-initrd. Users can add their own customizations in /etc/mkosi-initrd. A full self-contained UKI will be built and installed.

Once installed, the mkosi plugin can be enabled by writing initrd_generator=mkosi-initrd and layout=uki to /usr/lib/kernel/install.conf or to /etc/kernel/install.conf.

To enable this feature, install kernel-install/51-mkosi-addon.install into /usr/lib/kernel/install.d. Extra distro configuration for the addon can be configured in /usr/lib/mkosi-addon. Users can add their own customizations in /etc/mkosi-addon and /run/mkosi-addon. Note that unless at least one of the last two directories are present, the plugin will not operate.

This plugin is useful to enhance a vendor-provided UKI with local-only modifications.

To hack on mkosi itself you will also need mypy, for type checking, and pytest, to run tests. We check tests and typing in CI (see .github/workflows), but you can run the tests locally as well.

• Primary mkosi git repository on GitHub
• A re-introduction to mkosi — A Tool for Generating OS Images
• The mkosi OS generation tool story on LWN (2017)
• systemd-repart: Building Discoverable Disk Images and mkosi: Building Bespoke Operating System Images talks at All Systems Go! 2023
• Building RHEL and RHEL UBI images with mkosi an article in Fedora Magazine (2023)
• Building USIs with mkosi
• Constellation 💖 mkosi — Minimal TCB, tailor-made for measured boot
• Streamlining kernel hacking with mkosi-kernel
• mkosi-initrd: Building initrds out of distribution packages
• Running systemd integration tests with mkosi
• Arch Linux rescue image with mkosi
• Building vagrant images with mkosi
• Building images with mkosi on the Open Build Service (OBS)

Find us on Matrix at #mkosi:matrix.org.