WHEN: Working with mkosi configuration files, mkosi.conf, Include= directives. WHEN NOT: General Linux configuration, non-mkosi build systems.
Brief guide to mkosi's configuration system as used in frostyard image builds.
Prerequisites: mkosi v24+, just, root/sudo access. See
image-buildingskill for setup details.
mkosi composes configuration from multiple levels:
mkosi.conf (root) # Global settings: distribution, repos, output
├── mkosi.images/ # Image definitions (base + sysexts)
│ ├── base/mkosi.conf # Base image: core packages, format=directory
│ ├── dev/mkosi.conf # Sysext: development tools
│ ├── docker/mkosi.conf # Sysext: Docker runtime
│ └── ... # Each sysext has its own mkosi.conf
├── mkosi.profiles/ # Desktop image variants
│ ├── snow/ # Snow desktop profile
│ ├── snowloaded/ # Snow + all sysexts
│ └── ...
└── shared/ # Reusable fragments included via Include=
├── kernel/ # Kernel configs (backports, surface, stock)
├── packages/ # Package set definitions
├── outformat/ # Output format configs
└── sysext/ # Shared sysext scripts
The root config sets global defaults inherited by all images:
Distribution=debian, Release=trixieRepositories=main,contrib,non-free,non-free-firmwareCacheDirectory=mkosi.cache, Incremental=yesWithNetwork=true (needed for package downloads)Dependencies= lists all images that must build (base + all sysexts)BaseTrees=%O/base — all images layer on top of the base image outputPer-image repository configuration is possible via Repositories= or PackageManagerTrees= in the image's own mkosi.conf. Use PackageManagerTrees= to add custom APT sources lists.
Each subdirectory under mkosi.images/ defines one buildable image.
Base image (mkosi.images/base/mkosi.conf):
Format=directory — outputs a directory tree, not a disk imageBaseTrees=%O/base to layer on thisSysext images (e.g., mkosi.images/dev/mkosi.conf):
Format=sysext — outputs a system extensionOverlay=yes — only includes files not in the baseDependencies=base — requires base to build firstPostOutputScripts=%D/shared/sysext/postoutput/sysext-postoutput.shEnvironment=KEYPACKAGE=<pkg> — identifies the primary package for versioningProfiles define desktop image variants that compose:
shared/packages/shared/kernel/shared/outformat/Include= pulls in additional config fragments:
[Config]
Include=../../shared/packages/desktop.conf
../../shared/kernel/backports.conf
../../shared/outformat/image/image.conf
Paths are relative to the config file using the directive. Fragments are merged in order — later values override earlier ones for single-value keys; list keys accumulate.
Image configs in mkosi.images/ inherit all settings from the root mkosi.conf. Per-image settings override single-value keys; list keys (like Packages=) accumulate.
%D — source directory (repo root)%O — output directory for the current image%o — output path of the current imagemkosi.images/<name>/mkosi.conf with sysext boilerplate (copy from dev or 1password-cli)ImageId=, Output=, and Packages=Environment=KEYPACKAGE=<primary-package>mkosi.conf Dependencies=.transfer and .feature files (see sysext-authoring skill)mkosi.profiles/<name>/mkosi.conf[Config]
Include=../../shared/packages/<package-set>.conf
../../shared/kernel/<variant>.conf
../../shared/outformat/image/image.conf
Packages=, scripts, and environment variablesjust target in the justfile for the new profilesudo mkosi -f -i <name> --debugsudo mkosi shellDependencies= entry in root config