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.

You can install mkosi from your distribution with its package manager or the development version from git. The distribution packages are the preferred way to install mkosi.

The development version of mkosi might require tools from the systemd main branch, see the action.yaml for what we currently use in CI.

If you just want to give the development version of mkosi a quick spin you can run

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

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

python -m venv mkosivenv
mkosivenv/bin/pip install git+https://github.com/systemd/mkosi.git
# the mkosi binary is installed to mkosivenv/bin/mkosi

If you want to help develop mkosi you can run it from your clone of this repository by calling the module

python3 -m mkosi

when you are in the repository top level.

To use your local mkosi checkout without being in the top level of the repository you can either call the shim bin/mkosi or make an editable install into a virtual environment. 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 somewhere into your PATH. To make an editable install add --editable to either of the above examples using pip or pipx and exchange the URL of the repository for the path to your local checkout, e.g

pipx install --editable path/to/yout/local/checkout

For development 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.

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/

tools/generate-zipapp.sh

Besides the mkosi binary, you can also call mkosi via

python -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.

• Primary mkosi git repository on GitHub
• mkosi — A Tool for Generating OS Images introductory blog post by Lennart Poettering (2017)
• 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

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