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 build install the following packages:

Distribution | Package
--- | ---
Arch | arch-install-scripts
Debian | debootstrap, debian-archive-keyring, dpkg, aptAUR
Ubuntu | debootstrap, ubuntu-keyring, dpkg, aptAUR
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 command will create a bootable image with the latest Debian version and the package openssh-client installed:

    # mkosi -d debian -t gpt_ext4 -b --checksum --password password --package openssh-client,vim -o image.raw

systemd-nspawn can boot the resulting image:

    # systemd-nspawn -b -i image.raw

It can also be virtualized with QEMU/KVM:

    $ qemu-system-x86_64 -m 512 -smp 2 -bios /usr/share/ovmf/x64/OVMF_CODE.fd -drive format=raw,file=image.raw

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

### Using configuration files

The same image can be created by creating a configuration file:

    mkosi.default

    [Distribution]
    Distribution=debian
    Release=stretch

    [Output]
    Format=gpt_ext4
    Bootable=yes
    Output=image.raw

    [Packages]
    Packages=
             openssh-client
             vim

    [Validation]
    Password=password

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

### Configurations

Basic options can be specified as command-line arguments or in a file called `mkosi.default` in your current directory. Most important options:

Argument | Option in mkosi.default | Description
--- | --- | ---
`-d` |
    [Distribution]
    Distribution=
| The name of the distribution to install, supported are: `fedora, debian, ubuntu, arch, opensuse, mageia, centos, centos_epel, clear, photon, openmandriva, rocky, rocky_epel, alma, alma_epel, gentoo`
`-r` |
    [Distribution]
    Release=
| The version of the distribution: jessie, 21, …
`-t` |
    [Output]
    Format=
| Format of the image to create: gpt_ext4: Image file with GPT partition table and ext4 file system gpt_btrfs: Image file with GPT partition table and btrfs file system gpt_squashfs: Image file with GPT partition table and squashfs file system directory: A plain directory subvolume: A btrfs subvolume tar: A tar-ball of a plain directory
`-b` |
    [Output]
    Bootable=yes
| Make the image bootable
`--root-size` |
    [Output]
    RootSize=
| Size of the root file system
`-p` |
    [Packages]
    Packages=
| List of packages to be installed into the image
`-o` |
    [Output]
    Output=
| File/directory-Name
`--password` |
    [Validation]
    Password=password
| Set the initial root password

## See also

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

Category:

- Virtualization