{"id":13510887,"url":"https://github.com/systemd/mkosi","last_synced_at":"2025-04-10T11:28:50.475Z","repository":{"id":37264446,"uuid":"63237385","full_name":"systemd/mkosi","owner":"systemd","description":"💽 Build Bespoke OS Images","archived":false,"fork":false,"pushed_at":"2025-04-10T08:35:44.000Z","size":7982,"stargazers_count":1314,"open_issues_count":34,"forks_count":347,"subscribers_count":42,"default_branch":"main","last_synced_at":"2025-04-10T09:42:06.620Z","etag":null,"topics":["boot","btrfs","btrfs-subvolume","debian","disk-image","distro","efi","fedora","gpt","initramfs","initramfs-generator","initramfs-image","luks","mkosi","opensuse","partition","squashfs","ubuntu","verity"],"latest_commit_sha":null,"homepage":"https://mkosi.systemd.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/systemd.png","metadata":{"files":{"readme":"README.md","changelog":"NEWS.md","contributing":null,"funding":null,"license":"LICENSES/GPL-2.0-only.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-07-13T10:31:19.000Z","updated_at":"2025-04-10T08:35:48.000Z","dependencies_parsed_at":"2023-09-23T03:42:01.996Z","dependency_job_id":"d012b3c9-4948-4da5-9237-23d708478016","html_url":"https://github.com/systemd/mkosi","commit_stats":{"total_commits":4570,"total_committers":180,"mean_commits":25.38888888888889,"dds":0.3973741794310722,"last_synced_commit":"23b17713f4446ca5a9c78eb3e7c99e17afaff408"},"previous_names":[],"tags_count":36,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/systemd%2Fmkosi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/systemd%2Fmkosi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/systemd%2Fmkosi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/systemd%2Fmkosi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/systemd","download_url":"https://codeload.github.com/systemd/mkosi/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248208679,"owners_count":21065203,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["boot","btrfs","btrfs-subvolume","debian","disk-image","distro","efi","fedora","gpt","initramfs","initramfs-generator","initramfs-image","luks","mkosi","opensuse","partition","squashfs","ubuntu","verity"],"created_at":"2024-08-01T02:01:58.134Z","updated_at":"2025-04-10T11:28:49.923Z","avatar_url":"https://github.com/systemd.png","language":"Python","readme":"# mkosi — Build Bespoke OS Images\n\nA fancy wrapper around `dnf --installroot`, `apt`, `pacman`\nand `zypper` that generates customized disk images with a number of\nbells and whistles.\n\nFor a longer description and available features and options, see the [man\npage](mkosi/resources/man/mkosi.1.md) or run `mkosi documentation`. When\ngetting started see the `EXAMPLES` section.\n\n\u003ca href=\"https://repology.org/project/mkosi/versions\"\u003e\n    \u003cimg align=\"right\" src=\"https://repology.org/badge/vertical-allrepos/mkosi.svg?exclude_sources=site\u0026exclude_unsupported=1\" alt=\"Packaging status\"\u003e\n\u003c/a\u003e\n\n# Installation\n\nYou can install mkosi from your distribution using its package manager\nor install the development version from git. If you install mkosi using\nyour distribution's package manager, make sure it installs at least\nmkosi v16 or newer (Use `mkosi --version` to check). If your\ndistribution only packages an older version of mkosi, it is recommended\nto install mkosi using one of the alternative installation methods\nlisted below instead.\n\n## Running mkosi from the repository\n\nTo run mkosi straight from its git repository, you can invoke the shim\n`bin/mkosi`. The `MKOSI_INTERPRETER` environment variable can be set\nwhen using the `bin/mkosi` shim to configure the python interpreter used\nto execute mkosi. The shim can be symlinked to e.g. `~/.local/bin` to\nmake it accessible from the `PATH`. Note that to make this work you\nmight have to add `~/.local/bin` to your user's `PATH`.\n\n```shell\ngit clone https://github.com/systemd/mkosi\nln -s $PWD/mkosi/bin/mkosi ~/.local/bin/mkosi\nmkosi --version\n```\n\n## Python installation methods\n\nmkosi can also be installed straight from the git repository url using\n`pipx`:\n\n```shell\npipx install git+https://github.com/systemd/mkosi.git\nmkosi --version\n```\n\nwhich will transparently install mkosi into a Python virtual environment\nand a mkosi binary to `~/.local/bin`. This is, up to the path of the\nvirtual environment and the mkosi binary, equivalent to\n\n```shell\npython3 -m venv mkosivenv\nmkosivenv/bin/pip install git+https://github.com/systemd/mkosi.git\nmkosivenv/bin/mkosi --version\n```\n\nYou can also package mkosi as a\n[zipapp](https://docs.python.org/3/library/zipapp.html) that you can\ndeploy anywhere in your `PATH`. Running this will leave a `mkosi` binary\nin `builddir/`\n\n```shell\ngit clone https://github.com/systemd/mkosi\ncd mkosi\ntools/generate-zipapp.sh\nbuilddir/mkosi --version\n```\n\nBesides the mkosi binary, you can also call mkosi via\n\n```shell\npython3 -m mkosi\n```\n\nwhen not installed as a zipapp.\n\nPlease note, that the python module exists solely for the usage of the\nmkosi binary and is not to be considered a public API.\n\n## Installing packages from upstream repositories\n\nmkosi packages for Debian, Ubuntu, Fedora and SUSE are built from latest main\nand published as repositories for the respective distributions on OBS.\n[Follow these instructions to enable the appropriate repository](https://software.opensuse.org//download.html?project=system%3Asystemd\u0026package=mkosi).\n\n## kernel-install plugins\n\nmkosi can also be used as a kernel-install plugin to build initrds and addons.\nIt is recommended to use only one of these two plugins at a given time.\n\n### UKI plugin\nTo enable this feature, install `kernel-install/50-mkosi.install`\ninto `/usr/lib/kernel/install.d`. Extra distro configuration for the\ninitrd can be configured in `/usr/lib/mkosi-initrd`. Users can add their\nown customizations in `/etc/mkosi-initrd`. A full self-contained UKI will\nbe built and installed.\n\nOnce installed, the mkosi plugin can be enabled by writing\n`initrd_generator=mkosi-initrd` and `layout=uki` to `/usr/lib/kernel/install.conf`\nor to `/etc/kernel/install.conf`.\n\n### Addon plugin\nTo enable this feature, install `kernel-install/51-mkosi-addon.install` into\n`/usr/lib/kernel/install.d`. Extra distro configuration for the addon can be\nconfigured in `/usr/lib/mkosi-addon`. Users can add their own customizations in\n`/etc/mkosi-addon` and `/run/mkosi-addon`. Note that unless at least one of the\nlast two directories are present, the plugin will not operate.\n\nThis plugin is useful to enhance a vendor-provided UKI with local-only\nmodifications.\n\n# Hacking on mkosi\n\nTo hack on mkosi itself you will also need\n[mypy](https://github.com/python/mypy), for type checking, and\n[pytest](https://github.com/pytest-dev/pytest), to run tests. We check\ntests and typing in CI (see `.github/workflows`), but you can run the\ntests locally as well.\n\n# References\n\n* [Primary mkosi git repository on GitHub](https://github.com/systemd/mkosi/)\n* [A re-introduction to mkosi — A Tool for Generating OS Images](https://0pointer.net/blog/a-re-introduction-to-mkosi-a-tool-for-generating-os-images.html)\n* [The mkosi OS generation tool](https://lwn.net/Articles/726655/) story on LWN (2017)\n* [systemd-repart: Building Discoverable Disk Images](https://media.ccc.de/v/all-systems-go-2023-191-systemd-repart-building-discoverable-disk-images) and [mkosi: Building Bespoke Operating System Images](https://media.ccc.de/v/all-systems-go-2023-190-mkosi-building-bespoke-operating-system-images) talks at All Systems Go! 2023\n* [Building RHEL and RHEL UBI images with mkosi](https://fedoramagazine.org/create-images-directly-from-rhel-and-rhel-ubi-package-using-mkosi/) an article in Fedora Magazine (2023)\n* [Building USIs with mkosi](https://overhead.neocities.org/blog/build-usi-mkosi/)\n* [Constellation 💖 mkosi — Minimal TCB, tailor-made for measured boot](https://www.edgeless.systems/blog/constellation-mkosi-minimal-tcb-tailor-made-for-measured-boot/)\n* [Streamlining kernel hacking with mkosi-kernel](https://video.fosdem.org/2024/ub5132/fosdem-2024-2209-streamlining-kernel-hacking-with-mkosi-kernel.av1.webm)\n* [mkosi-initrd: Building initrds out of distribution packages](https://video.fosdem.org/2024/ua2118/fosdem-2024-2888-mkosi-initrd-building-initrds-out-of-distribution-packages.av1.webm)\n* [Running systemd integration tests with mkosi](https://video.fosdem.org/2024/ud2208/fosdem-2024-3431-running-systemd-integration-tests-with-mkosi.av1.webm)\n* [Arch Linux rescue image with mkosi](https://swsnr.de/archlinux-rescue-image-with-mkosi)\n* [Building vagrant images with mkosi](https://vdwaa.nl/mkosi-vagrant-images.html#mkosi-vagrant-images)\n\n## Community\n\nFind us on Matrix at [#mkosi:matrix.org](https://matrix.to/#/#mkosi:matrix.org).\n","funding_links":[],"categories":["Python","ubuntu","main() {"],"sub_categories":["Linux / Unix / BSD"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsystemd%2Fmkosi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsystemd%2Fmkosi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsystemd%2Fmkosi/lists"}