kiwi [global options] service <command> [<args>]

kiwi -h | --help
kiwi [--profile=<name>...]
    image <command> [<args>...]
kiwi [--debug]
    result <command> [<args>...]
kiwi [--profile=<name>...]
    system <command> [<args>...]
kiwi compat <legacy_args>...
kiwi -v | --version
kiwi help


KIWI is an imaging solution that is based on an image XML description. Such a description is represented by a directory which includes at least one config.xml or .kiwi file and may as well include other files like scripts or configuration data.

A collection of example image descriptions can be found on the github repository here: Most of the descriptions provide a so called JeOS image. JeOS means Just enough Operating System. A JeOS is a small, text only based image including a predefined remote source setup to allow installation of missing software components at a later point in time.

KIWI operates in two steps. The system build command combines both steps into one to make it easier to start with KIWI. The first step is the preparation step and if that step was successful, a creation step follows which is able to create different image output types.

In the preparation step, you prepare a directory including the contents of your new filesystem based on one or more software package source(s) The creation step is based on the result of the preparation step and uses the contents of the new image root tree to create the output image.

KIWI supports the creation of the following image types:

  • ISO Live Systems

  • Virtual Disk for e.g cloud frameworks

  • OEM Expandable Disk for system deployment from ISO or the network

  • File system images for deployment in a pxe boot environment

Depending on the image type a variety of different disk formats and architectures are supported.



Use Escape Sequences to print different types of information in colored output. The underlaying terminal has to understand those escape characters. Error messages appear red, warning messages yellow and debugging information will be printed light grey.


Print debug information on the commandline.


Specify log file. the logfile contains detailed information about the process.


Select profile to use. The specified profile must be part of the XML description. The option can be specified multiple times to allow using a combination of profiles


Specify an alternative shared cache directory. The directory is shared via bind mount between the build host and image root system and contains information about package repositories and their cache and meta data. The default location is set to /var/cache/kiwi


Select image build type. The specified build type must be configured as part of the XML description.


Show program version


$ git clone

$ kiwi --type vmx system build \
    --description kiwi-descriptions/suse/x86_64/suse-leap-15.1-JeOS \
    --target-dir /tmp/myimage

The Runtime Configuration File

KIWI supports an additional configuration file for runtime specific settings that do not belong into the image description but which are persistent and would be unsuitable for command line parameters.

The runtime configuration file must adhere to the YAML syntax. KIWI searches for the runtime configuration file in the following locations:

  1. ~/.config/kiwi/config.yml

  2. /etc/kiwi.yml

The parameters that can be changed via the runtime configuration file are illustrated in the following example:

  # Additional command line flags for `xz`
  # see `man xz` for details
  - options: -9e

  # Override the URL to the Open Build Service (i.e. how repository
  # paths starting with `obs://` will be resolved).
  # This setting is useful for building a KIWI appliance locally, which is
  # hosted on a custom OBS instance.
  # defaults to:
  - download_url:

  # Specifies whether the Open Build Service instance is public or
  # private
  # defaults to true
  - public: true | false

  # Configure whether the image bundle should contain a XZ compressed
  # image result or not.
  - compress: true | false

  # Specify the compression algorithm for compressing container
  # images. Invalid entries are skipped.
  # Defaults to `xz`.
  - compress: xz | none

  # Configure which tool KIWI will use to build ISO images. Invalid
  # entries are ignored.
  # Defaults to `xorriso`
  - tool_category: cdrtools | xorriso

  # Specify the OCI archive tool that will be used to create container
  # archives for OCI compliant images.
  # Defaults to `umoci`.
  - archive_tool: umoci | buildah

  # Configure the maximum image size. Either provide a number in bytes
  # or specify it with the suffix `m`/`M` for megabytes or `g`/`G` for
  # gigabytes.
  # If the resulting image exceeds the specified value, then KIWI will
  # abort with an error.
  # The default is no size constraint.
  - max_size: 700m

  # Provide a list of runtime checks that should be disabled. Checks
  # that do not exist but are present in this list are silently
  # ignored.
  - disable: check_image_include_repos_publicly_resolvable | \
      check_target_directory_not_in_shared_cache | \
      check_volume_label_used_with_lvm | \
      check_volume_setup_defines_multiple_fullsize_volumes | \
      check_volume_setup_has_no_root_definition | \
      check_container_tool_chain_installed | \
      check_boot_description_exists | \
      check_consistent_kernel_in_boot_and_system_image | \
      check_dracut_module_for_oem_install_in_package_list | \
      check_dracut_module_for_disk_oem_in_package_list | \
      check_dracut_module_for_live_iso_in_package_list | \
      check_dracut_module_for_disk_overlay_in_package_list | \
      check_efi_mode_for_disk_overlay_correctly_setup | \
      check_xen_uniquely_setup_as_server_or_guest | \
      check_mediacheck_only_for_x86_arch | \


This version of KIWI uses a different caller syntax compared to former versions. However there is a compatibility mode which allows to use a legacy KIWI commandline as follows:

$ kiwi compat \
    --build kiwi-descriptions/suse/x86_64/suse-leap-15.1-JeOS \
    --type vmx -d /tmp/myimage