Image Description

KIWI builds images from a description directory. The directory describes what packages to install, how to configure the target system, and which image types should be created from the prepared root tree.

Description Directory Layout

A description directory usually contains these files:

config.xml or *.kiwi

The main image description. It defines metadata, repositories, packages, users, image types, and optional profile-specific variants.

root/ or root.tar.gz

Overlay content copied into the prepared root tree after package installation.

config.sh

An optional shell hook executed near the end of the prepare step.

images.sh

An optional shell hook executed at the beginning of the create step.

config-cdroot.tar[.*]

Optional additional files for ISO-style images, such as licenses or offline documentation.

Referenced archives, drivers, certificate files, and include files

Additional resources referenced from the image description itself.

Minimal Example

The following description is enough to prepare a root tree and create a simple image from it:

<image schemaversion="8.5" name="example">
  <description type="system">
    <author>Example Author</author>
    <contact>example@example.invalid</contact>
    <specification>Small example image</specification>
  </description>

  <preferences>
    <version>1.0.0</version>
    <packagemanager>zypper</packagemanager>
    <type image="oem" filesystem="ext4"/>
  </preferences>

  <repository type="rpm-md">
    <source path="https://download.opensuse.org/distribution/leap/16.0/repo/oss"/>
  </repository>

  <packages type="image">
    <package name="bash"/>
  </packages>
</image>

Top-Level Schema Layout

The kiwi/schema/kiwi.rnc schema organizes the document below the <image> root element in this order:

Top-level sections

Section	Purpose	Main attributes and children	Reference
<image>	Root node of the description.	Required: name, schemaversion. Optional: displayname, id.	<image>
<include>	Insert the inner content of another XML description file.	from URI attribute.	<include>
<certificates>	Import additional CA certificates during the build.	target_distribution with one or more <certificate name="..."/> entries.	<certificates>
<description>	Define human-readable identity and ownership.	type plus <author>, <contact>, <specification>, and optional <license>.	<description>
<preferences>	Define versions, package manager behavior, and one or more image types.	Optional arch and profiles filters; includes <version>, <packagemanager>, <type>, locale, timezone, themes, and release settings.	<preferences>
<profiles>	Group conditional variants of the same description.	<profile> entries with name, description, arch, import, and optional <requires>.	<profiles>
<users>	Create or adjust users and groups in the image.	User records, group membership, home, shell, SSH keys, and password data.	<users>
<drivers>	Add driver files to the image description.	File references with optional profile filters.	<drivers>
<strip>	Remove files, libraries, or toolchains from the prepared root tree.	Optional type and matching entries for files or package content.	<strip>
<repository>	Point KIWI to package sources.	Repository type, source type, priority, GPG behavior, credentials, and source URLs.	<repository>
<containers>	Define container registry sources used by container-based builds.	One or more registry definitions and registry-specific credentials.	<containers>
<packages>	Define what KIWI installs, deletes, or imports.	type, optional profiles, patternType, bootstrap_package with package, collection, product, file, ignore, and archive entries.	<packages>
<extension>	Attach custom XML namespaces validated outside the built-in schema.	Arbitrary namespaced content.	<extension>

What to Configure First

When you create or review an image description, work in this order:

1. Start with <description> so the image has clear ownership and a purpose.

2. Add at least one <preferences> block with a version, package manager, and one or more type definitions.

3. Add the <repository> entries that provide the packages needed for the build.

4. Add one or more <packages> sections to populate the root tree.

5. Add optional sections such as <users>, <profiles>, or <certificates> only when the use case needs them.

Common Patterns

Use profiles when one description should build multiple variants.

<profiles>
  <profile name="VMX" description="VMware output"/>
  <profile name="CLOUD" description="Cloud output"/>
</profiles>

<preferences profiles="VMX">
  <version>1.0.0</version>
  <packagemanager>zypper</packagemanager>
  <type image="oem" format="vmdk" filesystem="ext4"/>
</preferences>

<preferences profiles="CLOUD">
  <version>1.0.0</version>
  <packagemanager>zypper</packagemanager>
  <type image="oem" format="qcow2" filesystem="ext4"/>
</preferences>

Use multiple package sections to separate bootstrap packages from the final image content.

<packages type="bootstrap">
  <package name="filesystem"/>
  <package name="glibc-locale"/>
</packages>

<packages type="image">
  <package name="bash"/>
  <package name="vim"/>
</packages>

Complete Schema Reference

The exhaustive element and attribute reference is documented in Schema Reference. That reference follows the schema in kiwi/schema/kiwi.rnc and covers:

• every top-level section allowed below <image>;

• all common and type-specific attributes of <preferences><type>;

• repository, package, user, profile, bootloader, storage, and container substructures; and

• examples for the most frequently used sections.

Use this page as the guide to the structure of a description directory and use Schema Reference as the schema-backed lookup for every valid section and attribute.

• Schema Reference