mkosi - ArchWiki

Jump to content
From ArchWiki

Related articles

- systemd
- systemd-nspawn
- Linux Containers
- Docker

mkosi stands for Make Operating System Image, and is a tool for generating an OS tree or image that can be booted.

## Installation

Install mkosi or mkosi-gitAUR. 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, dpkg, apt
Ubuntu | debootstrap, ubuntu-keyring, dpkg, apt
Fedora | dnf
OpenSUSE | zypper-gitAUR
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 mtools and mkosi's optional dependency systemd-ukify:

    # mkosi --distribution debian --format disk --bootable --checksum --root-password password --package linux-image-generic,systemd,systemd-boot,systemd-sysv,udev,dbus --package openssh-client,vim --output image.raw

systemd-nspawn can boot the resulting image:

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

It can also be virtualized with QEMU/KVM:

    # 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=stable

    [Output]
    Format=disk
    Output=image.raw

    [Content]
    Bootable=yes
    Packages=linux-image-generic,systemd,systemd-boot,systemd-sysv,udev,dbus

             openssh-client
             vim
    RootPassword=password

    [Validation]
    Checksum=yes

See bootable for more distro booting examples.

Tip: If you create a folder `mkosi.cache` in the current working directory, mkosi will save all downloaded packages there, so you can recreate images faster.

### 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

## See also

- Mkosi on Github
- Longer introduction by Poettering, one of its developers

Category:

- Virtualization