mkosi

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-git^AUR. Depending on what distribution you want to build 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-git^AUR
CentOS	dnf-legacy-utils^AUR

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

Installation

Basic usage

Create and boot a Debian image

Using configuration files

Configuration settings

See also