Releases · systemd/mkosi

We now handle unmerged-usr systems correctly
Builtin configs (mkosi-initrd, mkosi-tools) can now be included
using Include= (e.g. Include=mkosi-initrd)
The kernel-install plugin now uses the builtin mkosi-initrd config
so there's no need anymore to copy the full mkosi-initrd config into
/usr/lib/mkosi-initrd.
We don't require a build anymore for the journalctl and
coredumpctl verbs.
mkosi ssh works again when used with ToolsTree=default
We now use .zst instead of .zstd for compressed split artifacts
produced by systemd-repart.
systemd-repart uses a persistent temporary directory again for
assembling images instead of a tmpfs.
Added MicrocodeHost= setting to only include the CPU specific
microcode for the current host system.
The kernel-install plugin now only includes the CPU specific microcode
Introduced PackageCacheDirectory= to set the directory for package
manager caches. This setting defaults to a suitable location in the
system or user directory depending on how mkosi is invoked.
CacheDirectory= is only used for incremental cached images now.
Repository metadata is now synced once at the start of each image
build and never during an image build. Each image includes a snapshot
of the repository metadata in the canonical locations in /var so
that incremental images and extension images can reuse the same
snapshot. When building an image intended to be used with
BaseTrees=, disable CleanPackageMetadata= to make sure the
repository metadata in /var is not cleaned up, otherwise any
extension images using this image as their base tree will not be able
to install additional packages.
Implemented CacheOnly=metadata. Note that in the JSON output, the
value of CacheOnly= will now be a string instead of a boolean.
Added CompressLevel= to set the compression level to use.
Dropped experimental Gentoo support.
Added TriggerMatch= to specify multiple match sections of which only
one should be satisfied.
Added jq, attr, acl, git, sed, grep and findutils to
the default tools tree.
Added mkosi-install, mkosi-upgrade, mkosi-remove and
mkosi-reinstall scripts which allow writing scripts that are
independent of the package manager being used to build the image.
We now expand specifiers in Match section values
Made GPG key handling for Fedora rawhide more robust
If systemd-repart 256 or newer is available, mkosi will instruct it
to generate /etc/fstab and /etc/crypttab for the image if any
partition definitions contain the corresponding settings
(MountPoint= and EncryptedVolume=).
bash is now started in the debug shell instead of sh.
The default release for Ubuntu is now noble.
Ubuntu is now used as the default tools tree distribution for Ubuntu
instead of Debian.
Added mkosi vmspawn which boots the image with systemd-vmspawn.
Note that systemd-vmspawn is experimental and its interface may
still change. As such mkosi vmspawn is also considered experimental.
Note that systemd-vmspawn version 256 or newer is required.
Added SyncScripts= which can be used to update various build sources
before starting the image build.
The DISTRIBUTION= and RELEASE= environment variables are now set
when running scripts.
Added ToolsTreeRepositories= and ToolsTreePackageManagerTrees=.
Added RuntimeNetwork= to configure the networking used when booting
the image.
Added SecureBootKeySource= and VerityKeySource= to support signing
images with OpenSSL engines. Note that these settings require various
systemd tools to be version 256 or newer.
We don't clean up package manager metadata anymore unless explicitly
requested with CleanPackageManagerMetadata=yes when building
directory and tar images.

Fixed a bug in signing unsigned shim EFI binaries.
We now build an early microcode initrd in the mkosi kernel-install
plugin.
Added PackageDirectories= to allow providing extra packages to be
made available during the build.
Fixed issue where KernelModulesIncludeHost was including unnecessary
modules
Fixed --mirror specification for CentOS (and variants) and Fedora.
Previously a subdirectory within the mirror had to be specified which
prevented using CentOS and EPEL repositories from the same mirror. Now
only the URL has be specified.
We now mount package manager cache directories when running scripts on
the host so that any packages installed in scripts are properly
cached.
We don't download filelists on Fedora anymore
Nested build sources don't cause errors anymore when trying to install
packages.
We don't try to build the same tools tree more than once anymore when
building multiple images.
We now create the /etc/mtab compatibility symlink in mkosi's
sandbox.
We now always hash the root password ourselves instead of leaving it
to systemd-firstboot.
/srv and /mnt are not mounted read-only anymore during builds.
Fixed a crash when running mkosi in a directory with fewer than two
parent directories.
Implemented RepositoryKeyCheck= for apt-based distributions.

BuildSources= are now mounted when we install packages so local
packages can be made available in the sandbox.
Fixed check to see if we're running as root which makes sure we don't
do shared mounts when running as root.
The extension release file is now actually written when building
system or configuration extensions.
The nspawn settings are copied to the output directory again.
Incremental caching is now skipped when Overlay= is enabled as this
combination isn't supported.
The SELinux relabel check is more granular and now checks for all
required files instead of just whether there's a policy configured.
qemu-system-xxx binaries are now preferred over the generic qemu
and qemu-kvm binaries.
Grub tools from the tools tree are now used to install grub instead of
grub tools from the image itself. The grub tools were added to the
default tools trees as well.
The pacman keyring in tools trees is now only populated from the
Arch Linux keyring (and not the Debian/Ubuntu ones anymore).
gpg is allowed to access /run/pscsd/pscsd.comm on the host if it
exists to allow interaction with smartcards.

The current working directory is not mounted unconditionally to
/work/src anymore. Instead, the default value for BuildSources=
now mounts the current working directory to /work/src. This means
that the current working directory is no longer implicitly included
when BuildSources= is explicitly configured.
Assigning the empty string to a setting that takes a list of values
now overrides any configured default value as well.
The github action does not build and install systemd from source
anymore. Instead, ToolsTree=default can be used to make sure a
recent version of systemd is used to do the image build.
Added EnvironmentFiles= to read environment variables from
environment files.
We drastically reduced how much of the host system we expose to
scripts. Aside from /usr, a few directories in /etc, /tmp,
/var/tmp and various directories configured in mkosi settings, all
host directories are hidden from scripts, package managers and other
tools executed by mkosi.
Added RuntimeScratch= to automatically mount a directory with extra
scratch space into mkosi-spawned containers and virtual machines.
Package manager trees can now be used to configure every tool invoked
by mkosi while building an image that reads config files from /etc
or /usr.
Added SELinuxRelabel= to specify whether to relabel selinux files
or not.
Many fixes to tools trees were made and tools trees are now covered by
CI. Some combinations aren't possible yet but we're actively working
to make these possible.
mkosi qemu can now direct kernel boot s390x and powerpc images.
Added HostArchitecture= match to match against the host
architecture.
We don't use the user's SSH public/private keypair anymore for
mkosi ssh but instead use a separate key pair which can be
generated by mkosi genkey. Users using mkosi ssh will have to run
mkosi genkey once to generate the necessary files to keep
mkosi ssh working.
We don't automatically set --offline=no anymore when we detect the
Subvolumes= setting is used in a systemd-repart partition
definition file. Instead, use the new RepartOffline= option to
explicitly disable running systemd-repart in offline mode.
During the image build we now install UKIs/kernels/initrds to /boot
instead of /efi. While this will generally not be noticeable, users
with custom systemd-repart ESP partition definitions will need to add
CopyFiles=/boot:/ along with the usual CopyFiles=/efi:/ to their
ESP partition definitions. By installing UKIs/kernels/initrds to
/boot, it becomes possible to use /boot to populate an XBOOTLDR
partition which wasn't possible before. Note that this is also safe to
do before v20 so CopyFiles=/boot:/ can unconditionally be added to
any ESP partition definition files.
Added QemuFirmwareVariables= to allow specifying a custom OVMF
variables file to use.
Added MinimumVersion= to allow specifying the minimum required mkosi
version to build an image.
Added support for Arch Linux's debug repositories
Merged the mkosi-initrd project into mkosi itself. mkosi-initrd is now
used to build the default initrd.
Implemented mkosi-initrd for all supported distributions.
Added ShimBootloader= to support installing shim to the ESP.
Added sysext, confext and portable output formats. These will produce
signed disk images that can be used as sysexts, confexts and portable
services respectively.
Added QemuVsockConnectionId= to configure how to allocate the vsock
connection ID when QemUVsock= is enabled.
Added documentation on how to build sysexts with mkosi.
Global systemd user presets are now also configured.
Implemented WithDocs= for apt.
On supported package managers, locale data for other locales is now
stripped if the local is explicitly configured using Locale=.
All rpm plugins are now disabled when building images.
Added KernelModulesIncludeHost= and
KernelModulesInitrdIncludeHost= to only include modules loaded on
the host system in the image/initrd respectively.
Implemented RemovePackages= for Arch Linux.
Added useradd and groupadd scripts to configure these binaries to
operate on the image during builds instead on the host.
Added microcode support. If installed into the image, an early
microcode initrd will automatically be built and prepended to the
initrd.
A passwordless root account may now be created by specifying hashed:
The Autologin= feature was extended with support for arm64,
s390x and powerpc architectures.
Added SecureBootAutoEnroll= to control automatic enrollment of secureboot
keys separately from signing systemd-boot and generated UKIs.
ImageVersion= is no longer automatically appended to the output files,
instead this is automatically appended to Output= if not specified and
results in the %o specifier being equivalent to %i or %i_%v depending
on if ImageVersion= is specified.

Support for RHEL was added!
Added journalctl and coredumpctl verbs for running the respective tools on built directory or disk images.
Added a burn verb to write the output image to a block device.
Added a new esp output format, which is large similar to the existing uki output format but wraps it in a disk image with only an ESP.
Presets were renamed to Images. mkosi.images/ is now used instead of mkosi.presets/, the Presets= setting was renamed to Images= and the Presets section was merged into the Config section. The old names can still be used for backwards compatibility.
Added profiles to support building variants of the same image in one repository. Profiles can be defined in mkosi.profiles/ and one can be selected using the new Profile= setting.
mkosi will now parse mkosi.local.conf before any other config files if that exists.
Added a kernel-install plugin. This is only shipped in source tree and not included in the Python module.
Added a --json option to get the output of mkosi summary as JSON.
Added shorthand -a for --autologin.
Scripts with the .chroot extension are now executed in the image automatically.
Added rpm helper script to have rpm automatically operate on the image when running scripts.
Added mkosi-as-caller helper script that can be used in scripts to run commands as the user invoking mkosi.
mkosi-chroot will now start a shell if no arguments are specified.
Added WithRecommends= to configure whether to install recommended packages by default or not where this is supported. It is disabled by default.
Added ToolsTreeMirror= setting for configuring the mirror to use for the default tools tree.
WithDocs= is now enabled by default.
Added BuildSourcesEphemeral= to make source directories ephemeral when running scripts. This means any changes made to source directories while running scripts will be undone after the scripts have finished executing.
Added QemuDrives= to have mkosi create extra qemu drives and pass them to qemu when using the qemu verb.
Added BuildSources= match to match against configured build source targets.
PackageManagerTrees= was moved to the Distribution section.
We now automatically configure the qemu firmware, kernel cmdline and initrd based on what type of kernel is passed by the user via -kernel or QemuKernel=.
The mkosi repository itself now ships configuration to build basic bootable images that can be used to test mkosi.
Added support for enabling updates-testing repositories for Fedora.
GPG keys for CentOS, Fedora, Alma and Rocky are now looked up locally first before fetching them remotely.
Signatures are not required for local packages on Arch anymore.
Packages on opensuse are now always downloaded in advance before installation when using zypper.
The tar output is now reproducible.
We now make sure git can be executed from mkosi scripts without running into permission errors.
We don't create subdirectories beneath the configured cache directory anymore.
Workspace directories are now created outside of any source directories. mkosi will either use XDG_CACHE_HOME, $HOME/.cache or /var/tmp depending on the situation.
Added environment variable MKOSI_DNF to override which dnf to use for building images (dnf or dnf5).
The rootfs can now be modified when running build scripts (with all changes thrown away after the last build script has been executed).
mkosi now fails if configuration specified via the CLI does not apply to any image (because it is overridden).
Added a new doc on building rpms from source with mkosi (docs/building-rpms-from-source.md).
/etc/resolv.conf will now only be mounted for scripts when they are run with network access.

$SCRIPT was renamed to $CHROOT_SCRIPT. $SCRIPT can still be used
but is considered deprecated.
Added RuntimeTrees= setting to mount directories when booting images
via mkosi boot, mkosi shell or mkosi qemu. The directories are
mounted with a uid map that maps the user invoking mkosi to the root
user so that all files in the directory appear as if owned by the root
user in the container or virtual machine and any new files created in
the directories are owned by the user invoking mkosi. To make this
work in VMs, we use VirtioFS via virtiofsd. Note that this
requires systemd v254 or newer to be installed in the image.
Added support for booting directory images with mkosi qemu via
VirtioFS. When CONFIG_VIRTIOFS and CONFIG_VIRTIO_PCI are builtin
modules, no initramfs is required to make this work.
Added Include= or --include to include extra configuration files
or directories.
Added support for specifiers to access the current value of certain
settings during configuration file parsing.
mkosi will now exit with an error when no configuration was
provided.
Multiple scripts of the same type are now supported.
Custom distributions are now supported via the new custom
distribution. When using custom as the distribution, the rootfs must
be provided via base trees, skeleton trees or prepare scripts.
We now use local GPG keys for rpm based distributions if the
distribution-gpg-keys package is installed on the host.
Added RuntimeSize= to grow the image to a specific size before
booting it when using mkosi boot or mkosi qemu.
We now set MKOSI_UID and MKOSI_GID when running scripts which are
set to the uid and gid of the user invoking mkosi respectively. These
can be used to run commands as the user that invoked mkosi.
Added an Architecture= match
Initrds specified with Initrds= are now used for grub menuentries as
well.
ImageId= and ImageVersion= are now written to os-release as
IMAGE_ID and IMAGE_VERSION if provided.
We pass command line arguments passed to the build verb to the build
script again.
We added support for the "RHEL Universal Base Image" distribution.

Fixed bug where --autologin was broken when used in combination with
a tools tree when using a packaged version of mkosi.

Added ToolsTreePackages= to add extra packages to the default tools
tree.
Added SystemdVersion= match to match on the host's systemd version
Added Format= match to match on the configured output format
Presets= can now be configured in global configuration files to select
which presets to build
UKIs can now be booted using direct linux boot.
We don't try to make images UEFI bootable anymore on architectures
that do not support UEFI
Fixed --help to show all options again
We now warn when settings are configured in the wrong section

mkosi.version is now picked up from preset and dropin directories as
well following the usual config precedence logic
Removed the "first assignment wins" logic from configuration parsing.
Settings parsed later will now override earlier values
Removed the ! operator for lists. Instead, assign the empty string
to the list to remove all previous values.
Added support for configuring custom default values for settings by
prefixing their name in the configuration file with @.
Added QemuCdrom= to attach the image to the virtual machine as a
CD-ROM instead of a block device.
Added SectorSize= to set the sector size of the disk images built by
systemd-repart.
Added back grub support (BIOS/UEFI). Note that we don't install grub
on UEFI yet but we do add the necessary configuration and partitions.
Added Bootloader= option to configure which EFI bootloader to
install. Added uki option to install just the UKI without
systemd-boot and grub to generate grub configuration to chainload
into the built UKIs.
Added BiosBootloader= to configure whether grub for BIOS gets
installed or not.
Added QemuFirmware= to select which qemu firmware to use (OVMF,
Seabios or direct kernel boot).
Added QemuKernel= to specify the kernel that should be used with
direct kernel boot.
/var/lib/dbus/machine-id is now removed if it was added by a package
manager postinstall script.
The manifest is not generated by default anymore. Use
ManifestFormat=json to make sure the manifest is generated.
Added SourceDateEpoch= to enable more reproducible image builds.
Added Seed= to set the seed passed to systemd-repart.
Updated the default Fedora release to Fedora 39.
If ToolsTree= is set to default, mkosi will now build a default
tools tree containing all the necessary tools to build images. The
distribution and release to use can be configured with
ToolsTreeDistribution= and ToolsTreeRelease= or are determined
automatically based on the image being built.
Added uki output format. This is similar to cpio, except the cpio
is packaged up as a UKI with a kernel image and stub picked up from
the rootfs.

Migrated to systemd-repart. Many options are dropped in favor of specifying them directly
in repart partition definition files:
- Format=gpt_xxx options are replaced with a single "disk" options. Filesystem to use can now be specified with repart's Format= option
- Format=plain_squashfs (Can be reproduced by a single repart squashfs
  root partition combined with SplitArtifacts=yes)
- Verity= (Replaced by repart's Verity= options)
- Encrypt= (Replaced by repart's Encrypt= option)
- RootSize=, HomeSize=, VarSize=, TmpSize=, ESPSize=, SwapSize=, SrvSize=
  (Replaced by repart's size options)
- UsrOnly= (replaced with CopyFiles=/:/usr in a usr partition definition)
- OutputSplitRoot=, OutputSplitVerity=, (Replaced by repart's SplitName= option)
- OutputSplitKernel= (UKI is now always written to its own output file)
- GPTFirstLBA (Removed, no equivalent in repart)
- ReadOnly= (Replaced by repart's ReadOnly= option per partition)
- Minimize= (Replaced by repart's Minimize= option per partition)
- CompressFs= (No equivalent in repart, can be replicated by replacing mkfs.
  in $PATH with a script that adds the necessary command line option)
- MkSquashfs= (Can be replaced with a script in $PATH that invokes
  the correct binary)
We also remove the WithoutUnifiedKernelImages= switch as building unified
kernel images is trivial and fast these days.
Support for --qemu-boot was dropped
Support for --use-host-repositories was dropped, use --repository-directory instead
RepositoryDirectory was removed, use PackageManagerTrees= or SkeletonTrees= instead.
--repositories is now only usable on Debian/RPM based distros and can only be used to enable additional
repositories. Specifically, it cannot be used on Arch Linux anymore to add new repositories.
The _epel distributions were removed. Use --repositories=epel instead to enable
the EPEL repository.
Removed -stream from CentOS release specifiers. Instead of specifying 8-stream,
you know just specify 8.
Removed default kernel command line arguments rhgb, selinux=0 and audit=0.
Dropped --all and --all-directory as this functionality is better implemented by
using a build system.
mkosi now builds images without needing root privileges.
Removed --no-chown, --idmap and --nspawn-keep-unit options as they were made obsolete by moving to
rootless builds.
Removed --source-file-transfer, --source-file-transfer-final, --source-resolve-symlinks and
--source-resolve-symlinks-final in favor of always mounting the source directory into the build image.
--source-file-transfer-final might be reimplemented in the future using virtiofsd.
Dropped --include-dir option. Usage can be replaced by using --incremental and reading includes from
the cached build image tree.
Removed --machine-id in favor of shipping images without a machine ID at all.
Removed --skip-final-phase as we only have a single phase now.
The post install script is only called for the final image now and not for the build image anymore. Use the
prepare script instead.
--ssh-key, --ssh-agent, --ssh-port and --ssh-timeout options were dropped as the SSH support was
reimplemented using VSock. mkosi ssh can only be used with images booted with mkosi qemu. Use
machinectl to access images booted with mkosi boot. Use --extra-tree or --credential with the
.ssh.authorized_keys.root credentials as alternatives for provisioning the public key inside the image.
Only configuration files matching *.conf are parsed in dropin directories now.
Removed --qemu-headless, we now start qemu in the terminal by default and configure the serial console at
runtime. Use the new --qemu-gui option to start qemu in its graphical interface.
Removed --netdev. Can be replaced by manually installing systemd-networkd, putting a network file in the
image and enabling systemd-networkd.
If mkosi.extra/ or mkosi.skeleton/ exist, they are now always used instead of only when no explicit
extra/skeleton trees are defined.
mkosi doesn't install any default packages anymore aside from packages required by the distro or the base
filesystem layout package if there are no required packages. In practice, this means systemd and other
basic tools have to be installed explicitly from now on.
Removed --base-packages as it's not needed anymore since we don't install any packages by default anymore
aside from the base filesystem layout package.
Removed --qcow2 option in favor of supporting only raw disk images as the disk image output format.
Removed --bmap option as it can be trivially added manually by utilizing a finalize script.
The never value for --with-network was spun of into its own custom option --cache-only.
--bootable now defaults to auto. When set to auto, mkosi will generate a bootable image only if all
the necessary packages are installed. Documentation was added in docs/bootable.md on how a bootable image
can be generated on mainstream distros.
The RPM db is no longer rebuilt in bdb format on CentOS Stream 8. To be able to install packages on a
CentOS Stream 8 image with a RPM db in sqlite format, rewrite the db in bdb format using
rpm --rebuilddb --define _db_backend bdb.
Repositories are now only written to /etc/apt/sources.list if apt is installed in the image.
Removed the dependency on debootstrap to build Ubuntu or Debian images.
Apt now uses the keyring from the host instead of the keyring from the image. This means
debian-archive-keyring or ubuntu-archive-keyring are now required to be installed to build Debian or
Ubuntu images respectively.
--base-image is split into --base-tree and --overlay.
Removed --cache-initrd, instead, use a prebuilt initrd with Initrds= to avoid rebuilding the initrd all
the time.
Disk images are now resized to 8G when booted to give some disk space to play around with in the booted
image.
Removed --install-directory= option. This was originally added for caching the installation results, but
this doesn't work properly as it might result in leftover files in the install directory from a previous
installation, so we have to empty the directory before reusing it, invalidating the caching, so the option
was removed.
Build scripts are now executed on the host. See the SCRIPTS section
in the manual for more information. Existing build scripts will need
to be updated to make sure they keep working. Specifically, most paths
in scripts will need to be prefixed with $BUILDROOT to have them
operate on the image instead of on the host system. To ensure the host
system cannot be modified when running a script, most host directories
are mounted read-only when running a script to ensure a script cannot
modify the host in any way. Alternatively to making the script run on
the host, the script can also still be executed in the image itself by
putting the following snippet at the top of the script:
```
if [ "$container" != "mkosi" ]; then
    exec mkosi-chroot "$SCRIPT" "$@"
fi
```
Removed --tar-strip-selinux-context= option. We now label all files
properly if selinux is enabled and if users don't want the labels,
they can simply exclude them when extracting the archive.
Gentoo is now marked as experimental and unsupported and there's no
guarantee at all that it will work. Issues related to gentoo will
generally not receive attention from core maintainers. All gentoo
specific hacks outside of the gentoo implementation module have been
removed.
A verb documentation has been added. Calling mkosi with this verb will show
the documentation. This is useful when running mkosi during development to
always have the documentation in the correct version available. By default it
will try several ways to output the documentation, but a specific option can
be chosen with the --doc-format option. Distro packagers are encouraged to
add a file mkosi.1 into the mkosi/resources directory of the Python
package, if it is missing, as well es install it in the appropriate search
path for man pages. The man page can be generated from the markdown file
mkosi/resources/mkosi.md e.g via pandoc -t man -s -o mkosi.1 mkosi.md.
The man page can be generated from the markdown file via
tools/make-man-page.sh.
Fixed issue where not all packages and data files where included in
the generated python package.
mkosi doesn't try to unshare the network namespace anymore when it
doesn't have CAP_NET_ADMIN.
Fixed issue when the workspace was located in /tmp.
Don't try to run timedatectl or ssh-add when they're not installed.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Releases: systemd/mkosi

mkosi v21

Uh oh!

mkosi v20.2

Uh oh!

mkosi v20.1

Uh oh!

mkosi v20

Uh oh!

v19

Uh oh!

v18

Uh oh!

v17.1

Uh oh!

v17

Uh oh!

v16

Uh oh!

v15.1

Uh oh!