KIWI(8)

📦
version 10.3.10 · 5 versions
, in ubuntu stonking

💖 KIWI(8) — the kiwi manual, but make it slay 💖

okay bestie, sit down, grab a boba, because we're about to talk about KIWI NG — the imaging solution that builds entire operating system images and honestly? she's iconic for it. 🫶

✨ NAME ✨

kiwi — Creating Operating System Images 🎀

✨ SYNOPSIS ✨

like, here's literally how you call her:

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

kiwi-ng -h | --help
kiwi-ng [--profile=<name>...]
        [--setenv=<variable=value>...]
        [--temp-dir=<directory>]
        [--target-arch=<name>]
        [--type=<build_type>]
        [--logfile=<filename>]
        [--logsocket=<socketfile>]
        [--loglevel=<number>]
        [--debug]
        [--debug-run-scripts-in-screen]
        [--color-output]
        [--config=<configfile>]
        [--kiwi-file=<kiwifile>]
    image <command> [<args>...]
kiwi-ng [--logfile=<filename>]
        [--logsocket=<socketfile>]
        [--loglevel=<number>]
        [--debug]
        [--debug-run-scripts-in-screen]
        [--color-output]
        [--config=<configfile>]
    result <command> [<args>...]
kiwi-ng [--profile=<name>...]
        [--setenv=<variable=value>...]
        [--shared-cache-dir=<directory>]
        [--temp-dir=<directory>]
        [--target-arch=<name>]
        [--type=<build_type>]
        [--logfile=<filename>]
        [--logsocket=<socketfile>]
        [--loglevel=<number>]
        [--debug]
        [--debug-run-scripts-in-screen]
        [--color-output]
        [--config=<configfile>]
        [--kiwi-file=<kiwifile>]
    system <command> [<args>...]
kiwi-ng -v | --version
kiwi-ng help

(and that's the three services, periodt: service, image, result, system — each one takes its own <command> [<args>...] 💅)

✨ DESCRIPTION ✨

okay so KIWI NG is an imaging solution and the whole thing runs on an image XML description. that's the moment. 🦋

a description can be literally just a single config.xml, or a .kiwi file. or she can also bring extra files along — scripts, configuration data, the whole little friend group 💜.

a whole collection of example image descriptions lives in this GitHub repo: <https://github.com/OSInside/kiwi-descriptions>. most of those descriptions hand you a so-called appliance image. and an appliance is a small, text-based image that already has a predefined remote source setup baked in, so you can install the missing software components later. lowkey genius ngl.

so KIWI NG technically operates in two steps — but bestie, the system build command combines both of them into one, so you can just start using KIWI NG without a whole ritual. iconic behavior, honestly:

  • step one — prepare a directory that includes the contents of a new filesystem, based on one or more software package sources. 🌸
  • step two — take the prepared contents of that new image root tree and create the output image. ✨

and here's the vibe check on which image types KIWI NG supports making:

  • ISO Live Systems
  • virtual disk for, e.g., cloud frameworks
  • OEM expandable disk for system deployment from ISO or the network
  • filesystem images for deployment in a PXE boot environment

depending on the image type, different disk formats and architectures are supported. no cap. 👑

✨ GLOBAL OPTIONS ✨

  • --color-output — uses escape sequences to print different types of information in colored output 🌈. for this option to actually work though, the underlying terminal must support those escape characters. error messages appear in red, warning messages in yellow, and debugging information prints in light grey. so pretty, so fragile 💅
  • --config=<configfile> — use the specified runtime configuration file. this does not replace the standard lookup: the file's settings take the highest precedence. and a path that doesn't exist? that's an error, bestie, not a vibe 😭

independent of --config, KIWI NG always reads and merges every one of the following files that exist, with later entries overriding earlier ones: /usr/share/kiwi/kiwi.yml, every *.yml in /usr/share/kiwi/kiwi.yml.d/ (alphabetically), /etc/kiwi.yml, every *.yml in /etc/kiwi.yml.d/ (alphabetically), and ~/.config/kiwi/config.yml. and listen — both drop-in directories get scanned whether or not the corresponding main file exists. she's thorough like that. 🧚

merging happens at the top level only: a file that defines a section replaces that whole section from earlier files, rather than merging the keys inside it. (not me, not a deep merge, don't get it twisted 🙈) see The Runtime Configuration File <#runtime-config> for the further details.

  • --debug — prints debug information on the command line. same as: --loglevel 10.
  • --debug-run-scripts-in-screen — runs scripts called by KIWI NG in a screen session. 🖥️✨
  • --logfile=<filename> — specifies the log file. the logfile contains detailed information about the process. and the special call --logfile stdout sends all the information to standard out instead of writing to a file. we love a flexible queen 💖
  • --logsocket=<socketfile> — sends log data to the specified Unix Domain socket in the same format as with --logfile.
  • --loglevel=<number> — specifies the logging level as a number. further info about the available log levels can be found at: <https://docs.python.org/3/library/logging.html#logging-levels>. setting a log level displays all messages above the specified level. here's the level lore:
    • CRITICAL — numeric value 50
    • ERROR — numeric value 40
    • WARNING — numeric value 30
    • INFO — numeric value 20
    • DEBUG — numeric value 10
    • NOTSET — numeric value 0
  • --profile=<name> — selects a profile to use 🔥. the specified profile must be part of the XML description. and plot twist: you can specify this option multiple times to allow a combination of profiles. stacking profiles, we love to see it.
  • --setenv=<variable=value> — exports an environment variable and its value into the caller's environment. this option can be specified multiple times. yes bestie, multiple. go off. 💅
  • --shared-cache-dir=<directory> — specifies an alternative shared cache directory. this directory is shared via bind mount between the build host and the image root system, and it contains information about package repositories and their cache and metadata. the default location is /var/cache/kiwi. ⚠️ real talk though: this option is only accepted for the system service.
  • --temp-dir=<directory> — specifies an alternative base temporary directory. the provided path is used as a base directory to store temporary files and directories. the default is /var/tmp.
  • --target-arch=<name> — specifies an image architecture. by default, the host architecture is used as the image architecture. now here's the caveat, and it's a big one: if the specified architecture name does not match the host architecture (meaning you're requesting a cross-architecture image build 😭), you must configure the support for the image architecture and binary format on the building host. this must be done during the preparation stage, and it is beyond the scope of KIWI NG. so that one's on you, bestie — she's just the messenger.
  • --type=<build_type> — selects an image build type. the specified build type must be configured as part of the XML description.
  • --kiwi-file=<kiwifile> — the basename of the kiwi file that contains the main image configuration elements. if not specified, kiwi uses a file named config.xml or a file matching *.kiwi.
  • -v, --version — show the program version. ✨
  • help — show the manual page for the given service and command. 👑

✨ EXAMPLE ✨

here's the whole thing in action, and yes it's giving main character energy:

$ git clone https://github.com/OSInside/kiwi

$ sudo kiwi-ng system build \
    --description kiwi/build-tests/x86/leap/test-image-disk \
    --set-repo https://download.opensuse.org/distribution/leap/16.0/repo/oss \
    --target-dir /tmp/myimage

note the sudo? yeah. she's building a whole operating system. respect the process. 💜

✨ AUTHOR ✨

Marcus Schäfer 🫶

2020-2026, Marcus Schäfer

and that's the whole page, bestie. 🎀 this was kiwi, manual section 8 — the KIWI NG manual — version 10.3.10, dated Aug 13, 2026. go build something iconic with her. you got this. periodt. 💅✨💖

📦 where this page comes from