Welcome to KIWI NG
Build Linux images from one description in a predictable two-step workflow.
KIWI NG is a command-line image builder for Linux distributions. It creates bootable, reproducible images for virtual machines, cloud platforms, removable media, containers, and specialized deployment targets.
Note
This documentation covers KIWI Next Generation (KIWI NG) 11.1.16.
Build Architecture
KIWI NG builds from an image description and the repositories that provide the packages for it. In the prepare step, KIWI creates a new root tree. In the create step, KIWI converts that prepared root tree into one or more image artifacts.
- Diagram description:
The diagram shows two required inputs: an image description and the repositories that contain the packages used for the build. Both feed the prepare step, which creates a new root tree. The create step then turns that prepared root tree into one or more images such as disk, ISO, or container artifacts.
The image description directory typically contains:
config.xmlor a*.kiwifile with the image definition.Repository definitions that point to the package sources used during the build.
Optional overlays, archives, and shell hooks that customize the prepared root tree or the final image artifacts.
Why KIWI?
One source, multiple outputs: prepare a root filesystem once and create one or more image formats from it.
Declarative image definitions: keep image metadata, repositories, packages, users, and storage settings in a versioned description.
Broad target support: build for bare metal, virtual machines, cloud environments, live media, and containers.
Distribution-aware builds: work with the package managers and repository layouts used by the supported Linux distributions.
Controlled customization: extend builds with overlays, archives, and scripts when the schema alone is not enough.
Get Started
Start with Quick Start for a first build, Building Images for the build process and how to set up an image, and Image Description for the schema-backed reference for description files.
Note
Most chapters of this documentation reference example image descriptions
from the integration build tests, which are part of the KIWI NG source
repository in the build-tests directory. In addition, the
community image descriptions
offer examples for a wider range of distributions, and can also contain
image descriptions for certain use cases, such as desktop images.
System Requirements
To build images with KIWI NG, you need:
A recent Linux distribution. See Build Host Constraints for the tested targets.
Enough free disk space for the build root, caches, and resulting images. A minimum of 15 GB is recommended.
Python 3.9 or newer.
Git to clone image descriptions and example repositories.
Optionally, a virtualization environment such as QEMU to boot and inspect the resulting images.
Tip
Fewer requirements with kiwi-boxbuild
The kiwi-boxbuild tool, written in Rust, runs the build in a
self-contained virtual machine started from a runtime container.
The build host only needs podman and access to the KVM device
/dev/kvm. Neither KIWI NG and Python nor QEMU have to be
installed on it. See Building with kiwi-boxbuild for details.
kiwi-boxbuild can also be used on Windows 11, where it runs the
build in WSL2 with nested virtualization, see
Building on Windows 11. KIWI NG still builds
Linux images there, Windows is only the system it is called on.
The project officially tests and supports the following distributions:
Distribution |
Version |
|---|---|
43+ |
|
10+ |
|
10+ |
|
after April 2025 |
|
16.0+ |
|
26.04+ |
|
13+ |
|
after April 2025 |