v24

• The default kernel command line of console=ttyS0 (or equivalent for
  other architectures) has been removed. The required console=
  argument to have the kernel output to the serial console has to be
  added manually from v24 onwards.
• Support for installing local packages located in directories in
  BuildSources= was dropped. Instead, the packages can be made
  available for installation via PackageManagerTrees=.
• Configuration parsing was reworked to remove the need for the @
  specifier and to streamline building multiple images with
  mkosi.images/. If you were building multiple images with
  mkosi.images/, you'll need to adapt your configuration to the
  rework. Read the Building multiple images section in the
  documentation for more information.
• mkosi has gained the option to generate completion scripts for bash,
  fish and zsh. Packagers should generate the scripts during packaging
  and ship them in the appropriate places.
• Added support for CentOS Stream 10.
• mkosi now installs a separate mkosi-initrd script that can be used
  to build initramfs images intended for use on the local system.
• We do not automatically append centos-stream or fedora anymore to
  CentOS (and derivatives) and Fedora mirrors specified with Mirror=
  as not all mirrors store the repository metadata under these
  subdirectories. Users are now required to add these subdirectories
  themselves in Mirror=. If the EPEL repositories are enabled for
  CentOS Stream (and derivatives) and Mirror= is used, we look for the
  EPEL repositories in ../fedora relative to the mirror specified in
  Mirror=.
• We now support compressed tar archives wherever we already accept tar
  archives as input.
• We now always rerun the build if Format=none and don't remove
  previous outputs in that case (unless --force is specified). This
  allows using mkosi -t none to rerun the build scripts without
  removing the previous image. This can then be combined with
  RuntimeBuildSources=yes to make the build script outputs available
  in a booted container or virtual machine so they can be installed
  without having to rebuild the image.
• We now use virtconsole to provide the serial console when booting
  with qemu.
• root=PARTUUID and mount.usr=PARTUUID on the kernel command line
  are now automatically extended with the actual PARTUUID of the
  corresponding partition.
• All available OpenSUSE repositories are now supported and can be
  enabled with Repositories=.
• Building OpenSUSE aarch64 images is now supported
• mkosi dependencies was beefed up to handle more scenarios properly
• The default list of kernel modules that are always added to the
  initramfs was extended with various virtualization modules.
• Added a Repositories= match.
• Cached images are now invalidated if packages specified via
  PackageDirectories= change.
• Added VolatilePackageDirectories= which can be used to provide local
  packages that do not invalidate cached images.
• mkosi.pkgmngr is now used as the default path for
  PackageManagerTrees=.
• The package directory that build scripts can use to make built
  packages available for installation ($PACKAGEDIR) is now shared
  between all image builds. This means that packages built in earlier
  images and stored in $PACKAGEDIR become available for installation
  in all subsequent image builds.
• The default tools tree distribution is now chosen based on the host
  distribution instead of the target distribution.
• mkosi can now be invoked from the initramfs.

mkosi v23.1

v23.1

• Respin due to git tag mismatch

v23

• Added CleanScripts= to allow running custom cleanup code whenever
  mkosi cleans up the output directory. This allows cleaning up extra
  outputs produced by e.g. a build script that mkosi doesn't know about.
• Added ConfigureScripts= to allow dynamically modifying the mkosi
  configuration. Each configure script receives the current config as
  JSON on stdin and should output the new config as JSON on stdout.
• When building a UKI, we don't measure for the TPM SHA1 PCR bank
  anymore.
• All keys in the mkosi config JSON output are now in pascal case,
  except for credentials and environments, where the keys encode names
  of credentials and environment variables and are therefore case
  sensitive.
• Added various settings to allow running mkosi behind a proxy.
• Various fixes to kernel module filtering that should result in fewer
  modules being pulled into the default initrd when
  KernelModulesExclude= or KernelModulesInitrdExclude= are used.
• Added ToolsTreeDistribution= match.
• Removed vmspawn verb and replaced it with VirtualMachineMonitor=.
• New specifiers for various directories were added. %D resolves to
  the directory that mkosi was invoked in, %P to the current working
  directory, and %C to the parent directory of the config file.
• Added ForwardJournal= to have systemd inside a container/VM forward
  its journal to the specified file or directory.
• Systemd scopes are now allocated for qemu, swtpm, virtiofsd and
  systemd-journal-remote if available.
• The mkosi qemu virtual machine is now registered with
  systemd-machined if available.
• Added new oci output format
• Runtime trees without a target are now mounted to /root/src instead
  of a subdirectory of it (To have the same behaviour as
  BuildSources=).
• Added RuntimeBuildSources= to mount build and source directories
  when booting the image with mkosi nspawn or mkosi qemu.
• Introduced --append to allow command line settings to be parsed
  after parsing configuration files.
• distribution-release is not installed by default anymore on
  OpenSUSE.
• Setting QemuSmp= to 0 will now make qemu use all available CPUs
• Free page reporting and discard request processing are now enabled by
  default in VMs spawned by mkosi qemu.
• Added ToolsTreeCertificates= to allow configuring whether to use
  certificates and keys from the tools tree (if one is used) or the
  host.
• Added never for CacheOnly= to specify that repository metadata
  should always be refreshed.
• Renamed the none option for CacheOnly= to auto.
• Added ProxyExclude= to configure hostnames for which requests should
  not go through the configured proxy.
• The default tools tree is now reused on incremental builds.
• Added VolatilePackages= and InitrdVolatilePackages= to configure
  packages that should be installed after executing build scripts and
  which should not be cached when using Incremental=.
• PackageDirectories= now has an associated default path
  mkosi.packages.
• reprepro is now used to generate local apt repositories.
• Support for BSD tar/cpio was dropped.
• When both ExtraSearchPaths= and ToolsTree= are used, mkosi will
  now prefer running a binary found in ExtraSearchPaths= without the
  tools tree over running the binary from the tools tree. If a binary is
  not found in ExtraSearchPaths=, the tools tree is used instead.
• An artifact directory is now made available when running scripts which
  can be used to pass around data between different scripts. mkosi will
  also look for microcode and initrds in the artifact directory under
  the io.mkosi.microcode and io.mkosi.initrd subdirectories.
• Added Environment= match setting to check for environment variables
  defined with the Environment= setting.
• The basesystem package is now always installed in Fedora and
  CentOS images instead of the filesystem package.
• The qemu, shell and boot verbs do not automatically build the
  image anymore unless --force is specified.
• SplitArtifacts= is now supported for the portable, sysext and
  confext outputs.
• The WithDocs= option was implemented for pacman-based distributions.
• The default Fedora release was bumped to 40.
• QemuSwtpm= can now be used with QemuFirmware= set to linux or
  bios.
• Added UnitProperties= to allow configure properties on the scopes
  generated by systemd-nspawn and systemd-run.
• mkosi now only builds a single default tools tree per build using the
  settings from the last regular image that we'll build.
• Configure scripts are now only executed for verbs which imply an image
  build and are executed with the tools tree instead of without it.
• $QEMU_ARCHITECTURE is now set for configure scripts to easily allow
  scripts to figure out which qemu binary will be used to run qemu.
• A file ID can now be specified for QemuDrives=. This allows adding
  multiple qemu drives that are backed by the same file.
• mkosi doesn't fail anymore if images already exist when running
  mkosi build.
• Image names from mkosi.images/ are now preferred over the specified
  image ID when determining the output filename to use for an image.
• --include now has a shorthand option -I.
• The WITH_NETWORK environment variable is now passed to build and
  finalize scripts.
• We now clamp mtimes to the specified source date epoch timestamp
  instead of resetting all mtimes. This means that we won't touch any
  mtimes that are already older than the given source date epoch
  timestamp.
• Removed support for CentOS 8 Stream as it is now EOL.
• The coredumpctl and journalctl verbs now operrate on the path
  specified in ForwardJournal= if one is set.
• Added UnifiedKernelImageFormat= format setting to allow configuring
  the naming of unified kernel images generated by mkosi.
• The versionlock plugin is now enabled by default for dnf with a noop
  configuration.
• Repositories= is now implemented for zypper.
• KernelModulesInclude= and KernelModulesInitrdInclude= now take the
  special values host and default to include the host's loaded
  modules and the default kernel modules defined in mkosi-initrd
  respectively.
• KernelModulesIncludeHost= and KernelModulesInitrdIncludeHost= are
  now deprecated.
• Added mkosi dependencies to output the list of packages required by
  mkosi to build and boot images.

mkosi v22

• We'll now try to delete btrfs subvolumes with btrfs subvolume delete
  first before falling back to recursively deleting the directory.
• The invoking user is now always mapped to root when running sync
  scripts. This fixes an issue where we would fail when a package
  manager tree or skeleton tree contained a /usr directory as we would
  not have permissions to run mount in the sandbox.
• We now use qemu's official firmware descriptions to find EDK2/OVMF
  UEFI firmware. Addititionally, QemuFirmware=uefi now boots without
  SecureBoot support, and QemuFirmware=uefi-secure-boot was introduced
  to boot with SecureBoot support. By default we will still boot with
  SecureBoot support if QemuFirmware=auto.
• Added support for QemuFirmwareVariables=custom and
  QemuFirmwareVariables=microsoft to use OVMF/EDK2 variables with
  either the user's custom keys enrolled or with the Microsoft keys
  enrolled.
• Added UnifiedKernelImages= to control whether we generate unified
  kernel images or not.
• Bootloader=grub will now generate a grub EFI image and install it.
  If SecureBoot= is enabled and ShimBootloader= is not set to
  signed, the grub EFI image will be signed for SecureBoot.
• ShimBootloader=signed will now also instruct mkosi to look for and
  install already signed grub, systemd-boot, kernel and UKI binaries.
• We now build grub images with a fixed set of modules and don't copy
  any grub modules to the ESP anymore.
• The configuration is now made available as a JSON file to all mkosi
  scripts via the $MKOSI_CONFIG environment variable.
• $PROFILE is now set for all mkosi scripts containing the value of
  Profile= if it is set.

mkosi v21

• 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.

mkosi v20.2

• 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.

mkosi v20.1

• 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.

mkosi v20

• 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.

v19

• 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.

v18

• $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.

v17.1

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