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 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 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
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.
Find us on Matrix at #mkosi:matrix.org.