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 -f build

$ mkosi clean

$ mkosi help

mkosi [options] {build|shell|boot|vm|ssh|clean|summary|genkey|help}

mkosi builds customized, modern Linux OS images. It wraps package managers (dnf, apt, pacman, zypper) to generate disk images, container images, and unified kernel images with extensive customization options.
Supported output formats include raw GPT disk images, plain directories, tar and CPIO archives, unified kernel images (UKI), and OCI-compatible images. The tool supports multiple distributions and can create bootable images with systemd-boot or GRUB.
Configuration is read from mkosi.conf files, allowing declarative image definitions with support for profiles, conditional sections, and modular configurations.

build

Generate the image (default if no verb specified)

Interactive shell in built image via systemd-nspawn container

Boot systemd in image container

Boot image in virtual machine using QEMU

Connect to booted VM via SSH

Remove build artifacts

Display human-readable configuration overview

Output all loaded configuration file contents

Write image to block device

Generate SecureBoot keypairs

Replace existing output; repeat for cache purge

Enable caching between builds

Change to directory before processing

Target distribution: fedora, debian, ubuntu, arch, opensuse, etc.

Specific distribution version

Output type: directory, tar, disk, uki, etc.

Enable verbose output

Running mkosi on a filesystem with reflink support (XFS, btrfs) significantly improves performance. SELinux may block sshd access to VSock when connecting to VMs. Incremental build cache invalidation is basic; use -ff for clean rebuilds. Some features require root privileges.

mkosi is part of the systemd project, developed by Lennart Poettering and others. It was designed to build modern, legacy-free Linux images using systemd components like systemd-nspawn, systemd-repart, and unified kernel images. The tool emphasizes reproducibility and image-based deployments.

systemd-nspawn(1), systemd-repart(8), qemu(1)