Jump to content

# mkosi

From ArchWiki

Related articles

- systemd
- systemd-nspawn
- Linux Containers
- Docker

mkosi stands for Make Operating System Image, and is a tool for easily building customized OS images. It's a fancy Python wrapper around dnf, apt, pacman and zypper that may generate disk images with a number of bells and whistles.

It has nifty features like:

- `no_new_privileges` to build images as an unpriviliged user
- An Overlay filesystem to re-use existing distribution package caches reducing disk space requirements
- Deep Freedesktop.org and systemd integration
- Wide range of output formats like Raw GPT disk image, plain directory, tar, cpio and USI / UKI.

The project is actively maintained and provides mkosi(1) for customizing images across various distributions.

On Arch Linux, mkosi can be used to build bootable Unified Kernel Images (UKI), including those signed for Secure Boot. Creating images with encrypted LUKS volumes is as straightforward as defining `Passphrase=` in `mkosi.conf`. Package lists can be defined directly in the `mkosi.default` file under the `Packages=` section, and additional files or configuration can be added using overlay directories such as `mkosi.extra/`.

mkosi has a strong focus on developer workflows such as testing, debugging, and producing minimal, production-ready images. A common use case involves adding a `mkosi.default` configuration file to a project (e.g. written in C or Python), which then allows automated image generation tailored to the project’s needs.

During the build process, mkosi can create a temporary development image that includes headers and tooling, compile the project within it, run tests, and then discard this image. It subsequently builds a second image without development dependencies, containing only the resulting build artifacts and any other explicitly configured packages.

This resulting image is minimal, self-contained, and suitable for deployment via tools such as RAUC, or OSTree, making it well-suited for automated provisioning of servers, embedded systems, or IoT targets.

Note It is highly recommended to run mkosi on a File system that supports reflinks such as XFS and Btrfs and to keep all related directories on the same file system. This allows mkosi to create images very quickly by using reflinks to perform copying via copy-on-write operations.

## Installation

Install mkosi. Depending on what distribution you want to use in your OS tree/image, install the following packages:

Distribution | Package
--- | ---
Arch | arch-install-scripts
Debian | debootstrap, debian-archive-keyring, apt
Ubuntu | debootstrap, ubuntu-keyring, apt
Fedora | dnf
OpenSUSE | zypper
CentOS | dnf-legacy-utilsAUR

## Basic usage

You can create an image by just running it without any arguments:

    $ mkosi

You can specify option as arguments or by editing files in the current folder.

### Create and boot a Debian image

The following example will create a bootable image with the latest Debian version and packages openssh-client and vim installed. This command requires mkosi's optional dependencies mtools and systemd-ukify. Depending on the image, can also be built by an unprivileged (non-root) user:

    $ mkosi --distribution debian --release bookworm --format disk --checksum --root-password password --include mkosi-vm --package openssh-client,vim --repository-key-fetch=yes --output image.raw

systemd-nspawn can boot the resulting image:

    # systemd-nspawn --boot --image image.raw

It can also be virtualized with QEMU/KVM or with systemd-vmspawn(1):

    $ mkosi --output image.raw --qemu-smp 2 qemu

You can also write this image to a USB drive and use it to boot your computer.

### Using configuration files

The same Debian image can be created using a configuration file, `mkosi.conf`, and then run mkosi without any arguments:

    mkosi.conf

    [Distribution]
    Distribution=debian
    Release=bookworm
    RepositoryKeyFetch=true

    [Output]
    Format=disk
    Output=image.raw

    [Include]
    Include=mkosi-vm

    [Content]
    Bootable=yes
    Packages=openssh-client
             vim
    RootPassword=password

    [Validation]
    Checksum=yes

The built-in `mkosi-vm` profile adds the necessary packages in order to run a system and is maintained by the mkosi maintainers.

Downloaded package files and temporary build files are stored in the home cache directory or in `/var/cache/mkosi` and `/var/tmp`.

### Configuration settings

Settings can be specified as command-line arguments or, for example, in a file called `mkosi.conf` in the current directory. The most important settings are:

Command line | Configuration file | Description
--- | --- | ---
`--distribution` |
    [Distribution]
    Distribution=
| Name of the distribution to install. Supported are: `fedora, debian, ubuntu, arch, opensuse, mageia, centos, openmandriva, rocky, alma`
`--release` |
    [Distribution]
    Release=
| Version of the distribution: a numeric string or a distribution version name (`bookworm, …`)
`--format` |
    [Output]
    Format=
| Format of the image to create. For example: directory: plain directory disk: image file with GPT partition table tar: tarball of a plain directory
`--output` |
    [Output]
    Output=
| Name of the image file or directory
`--output-directory` |
    [Output]
    OutputDirectory=
| Location of the image file or directory (and other generated artifacts)
`--bootable` |
    [Content]
    Bootable=
| Enable or disable generation of a bootable image: `yes, no`
`--package` |
    [Content]
    Packages=
| List of packages to be installed into the image: (multi) line and/or comma separated list
`--root-password` |
    [Content]
    RootPassword=
| Initial root password

## Usage as initramfs generator

Mkosi provides a kernel-install plugin to build an initramfs, similarly to mkinitcpio or dracut.

In order to use it, install cpio and edit the kernel-install configuration file:

    /etc/kernel/install.conf

    initrd_generator=mkosi-initrd

Note The generated initramfs are much larger than the ones generated by mkinitcpio. The initramfs size can be significantly reduced by configuring zstd compression via the `CompressLevel=` Output option.

## See also

- Mkosi on Github
- Longer introduction by Poettering, one of its developers
- A re-introduction to mkosi by Daan De Meyer, the current maintainer
- Building Arch Linux USIs with mkosi
- Creating Arch Linux rescue image with Secure Boot
- Jelle's video presentation at All Systems Go on creating Arch Linux images using mkosi

Category:

- Virtualization

mkosi
Add topic