mkosi

Show current build configuration to verify what would be built

$ mkosi summary

$ mkosi build --distribution [fedora|debian|ubuntu|arch|opensuse|...]

$ mkosi shell

$ mkosi qemu

$ mkosi help

mkosi [OPTIONS...] [COMMAND]
Common commands:
mkosi build: Builds the operating system image.
mkosi clean: Cleans up build artifacts.
mkosi shell: Spawns an interactive shell inside the build environment.

--distribution=NAME
    Specify the base distribution (e.g., fedora, debian) for the image.

--size=SIZE
    Set the final image size (e.g., 5G for 5 Gigabytes, 100M for 100 Megabytes).

--format=FORMAT
    Choose the output image format (e.g., raw, qcow2, tar, directory).

--output=FILE
    Define the name and path for the generated image file.

--kernel
    Include a Linux kernel in the created image.

--extra-packages=PKGS
    Install additional space-separated packages into the image.

--ssh
    Enable the SSH daemon in the image and optionally create a user for SSH access.

--qemu-user-static
    Enable QEMU user-mode emulation binaries for cross-architecture builds.

--config-file=PATH
    Specify an alternative mkosi.conf file to use instead of the default.

--force
    Overwrite existing image files without prompting for confirmation.

--debug
    Enable verbose debugging output during the build process for troubleshooting.

--shell
    Run an interactive shell within the build environment instead of proceeding with the full build.

mkosi (Make Operating System Image) is a powerful and versatile script designed for creating reproducible operating system images. It automates the process of building various types of images, including raw disk images, QCOW2 virtual disk images, and tarball root file systems. mkosi supports a wide range of Linux distributions like Fedora, Debian, Arch Linux, and openSUSE.

A core strength of mkosi lies in its use of systemd-nspawn containers, which provide an isolated and consistent build environment. This isolation ensures that the build process is not affected by the host system's configuration, leading to highly reproducible images. Users define the image's properties, such as included packages, services, kernel, and custom scripts, through a declarative mkosi.conf file.

mkosi is particularly useful for developers needing consistent test environments, for creating appliance images, or for deploying custom systems. Its focus on reproducibility and integration with modern Linux tooling makes it a valuable asset for modern system development and deployment workflows. It simplifies what traditionally can be a complex and error-prone process.

mkosi typically requires root privileges for operations involving image creation and systemd-nspawn container management. Builds can consume significant disk space and network bandwidth, especially when downloading base images and packages for the first time. The tool is tightly integrated with systemd components, making it most effective in systemd-centric environments.

The primary method for configuring mkosi builds. This declarative file specifies the distribution, packages, services, kernel, boot loader, user accounts, and custom scripts (e.g., mkosi.postinst, mkosi.clean) to be included in the image. Its flexibility allows for highly customized image creation.

mkosi is designed with reproducibility in mind. By isolating the build environment using systemd-nspawn and specifying dependencies declaratively, it aims to produce identical images from the same input configuration, which is critical for consistent deployments and debugging.

mkosi emerged from the systemd project, primarily developed by Lennart Poettering and collaborators, to address the need for a simple, reproducible, and robust way to create operating system images. Its development leveraged systemd-nspawn's capabilities, allowing for secure and isolated build environments. It gained prominence as a convenient tool for systemd developers and users for crafting consistent development, testing, and deployment images.

systemd-nspawn(1), qemu-img(1), debootstrap(8), dnf(8), apt(8), pacman(8), virt-builder(1)