Awesome Open Source
Awesome Open Source

mkosi Build Bespoke OS Images

A fancy wrapper around dnf --installroot, debootstrap, 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.

Packaging status


Installing mkosi is easy, as it has no runtime Python dependencies (you will need all the tools to format filesystems and bootstrap the distribution appropriate for your image, though).

If you just want the main branch you can run

python3 -m pip install --user git+

If you want to hack on mkosi do

# clone either this repository or your fork of it
git clone
cd mkosi
python3 -m pip install --user --no-use-pep517 --editable .

This will install mkosi in editable mode to ~/.local/bin/mkosi, allowing you to use your own changes right away.

For development you also need mypy, for type checking, pytest, to run tests, and black, for code formatting. We check tests, typing and code formatting 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/


Python module

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.

git blame

When using git blame, be sure to add --ignore-revs-file .git-blame-ignore-revs to the arguments to ignore irrelevant code formatting commits. This can be set permanently via the blame.ignoreRevsFile git option.


Related Awesome Lists
Top Programming Languages
Top Projects

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Python (809,126
Git (34,487
Operating System (15,393
Debian (8,695
Formatter (6,572
Legacy (3,522
Efi (1,594
Opensuse (762
Btrfs (389
Gpt (122
Disk Image (91
Luks (77
Squashfs (28
Btrfs Subvolume (5
Mkosi (4