KIWI::SYSTEM::BUILD(8)

📦
version 11.1.1 · 12 versions
, in epel 10

💖 NAME 💖

okay bestie, welcome to KIWI::SYSTEM::BUILD(8) from KIWI NG ✨ — the manual page for kiwi::system::build, which does exactly this: Build image in combined prepare and create step. That's the whole vibe: one command, prepare plus create, no separate little steps to babysit 💅.

🌸 SYNOPSIS 🌸

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

kiwi-ng system build --help
kiwi-ng system build --description=<directory> --target-dir=<directory>
    [--allow-existing-root]
    [--clear-cache]
    [--ignore-repos]
    [--ignore-repos-used-for-build]
    [--set-repo=<source,type,alias,priority,imageinclude,package_gpgcheck,{signing_keys},components,distribution,repo_gpgcheck,repo_sourcetype>]
    [--set-repo-credentials=<user:pass_or_filename>]
    [--add-repo=<source,type,alias,priority,imageinclude,package_gpgcheck,{signing_keys},components,distribution,repo_gpgcheck,repo_sourcetype>...]
    [--add-repo-credentials=<user:pass_or_filename>...]
    [--add-package=<name>...]
    [--add-bootstrap-package=<name>...]
    [--ca-cert=<cert-file>...]
    [--ca-target-distribution=<suse|redhat|debian|archlinux>]
    [--delete-package=<name>...]
    [--set-container-derived-from=<uri>]
    [--set-container-tag=<name>]
    [--add-container-label=<name=value>...]
    [--set-type-attr=<attribute=value>...]
    [--set-release-version=<version>]
    [--signing-key=<key-file>...]

🦋 DESCRIPTION 🦋

So build is the main-character command: it builds an image in one step by combining the preparation and building steps, which means you can create an image with a single command. Iconic behavior, truly 🫶.

The build command creates the root directory of the image under <target-dir>/build/image-root and writes a log file at <target-dir>/build/image-root.log. The resulting image files are created in the specified target directory. Slay.

✨ OPTIONS ✨

  • --add-bootstrap-package=<name> — specifies a package to install as part of the early KIWI NG bootstrap phase. You can specify this option multiple times, bestie.
  • --add-container-label=<name=value> — adds a container label in the container configuration metadata. If the label with the provided key-value pair is already defined in the XML description, this overwrites it. Rude but useful 💅.
  • --add-package=<name> — specifies a package to add (install). This option can be specified multiple times.
  • --add-repo=<source,type,alias,priority,imageinclude,package_gpgcheck,{signing_keys},components,distribution,repo_gpgcheck,repo_sourcetype> — adds a new repository to the existing repository setup in the XML description. This option can be specified multiple times. For details about the possible option values, see the --set-repo information below.
  • --add-repo-credentials=<user:pass_or_filename> — for uri://user:pass@location repositories, sets the user and password associated with an add-repo specification. If the provided value describes a filename in the filesystem, the first line of that file is used as credentials. Sneaky little credential source, love that for you 🔥.
  • --allow-existing-root — uses an existing root directory from a previous build attempt. Use with caution, because this can cause an inconsistent root tree if the existing contents do not fit the previous image type setup. No cap, be careful with this one 😭.
  • --clear-cache — deletes the repository cache for each of the used repositories before installing any package. This is useful when an image build validates the signature of the package from the original repository source for any build. Some package managers unconditionally trust the contents of the cache, which works for cache data dedicated to one build. In the case of KIWI NG, the cache is shared between multiple image builds on that host for performance reasons. So yeah, cache drama — handle it.
  • --ca-cert=<cert-file> — adds a cert file to the directory storing additional local CA certificates. The import will occur immediately after the bootstrap process, where the required CA update tooling is expected to be installed. This option is useful for situations where certificates are not packaged, or the certificates are required during the build process, e.g., due to proxy servers in the build environment that need certificates in chroot. This option can be specified multiple times. Certificates are having a moment 🎀.
  • --ca-target-distribution=<suse|redhat|debian|archlinux> — specifies the target distribution for the import of certificates via the --ca-cert option(s) and/or the provided <certificates> from the image description. The selected distribution is used in KIWI to map the distribution-specific CA storage path and update tool for the import process.
  • --delete-package=<name> — specifies a package to delete. This option can be specified multiple times. Bye bestie 👋.
  • --description=<directory> — the path to an XML description. This is a directory containing at least one config.xml or *.kiwi XML file.
  • --ignore-repos — ignores all repository configurations from the XML description. This option is used in combination with the --add-repo option. Otherwise, there are no repositories available for an image build, which leads to an error. So like, don't forget the add-repo bestie, fr fr.
  • --ignore-repos-used-for-build — works the same way as --ignore-repos, except that repository configuration with the imageonly attribute set to true is not ignored.
  • --set-repo=<source,type,alias,priority,imageinclude,package_gpgcheck,{signing_keys},components,distribution,repo_gpgcheck,repo_sourcetype> — overwrites the first repository entry in the XML description with the provided information:
    • source — source URL pointing to a package repository that must be in a format supported by the selected package manager. See the URI_TYPES section for details about the supported source locators.
    • type — repository type: rpm-md, apt-deb.
    • alias — an alias name for the repository. If not specified, KIWI NG generates an alias name as a result of a hex representation from uuid4. While the hex is used to uniquely identify the repository, it is not descriptive. We recommend using descriptive aliases.
    • priority — a number indicating the repository priority. How the value is evaluated depends on the selected package manager. Refer to the package manager documentation for details about the supported priority ranges and their meaning.
    • imageinclude — set to either true or false to indicate if the repository is part of the system image repository setup or not.
    • package_gpgcheck — set to either true or false to indicate if the repository should validate the package signatures.
    • {signing_keys} — a list of signing keys enclosed in curly brackets and delimited by a semicolon. The reference to a signing key must be provided in the URI format.
    • components — a component list for Debian-based repos as a space-delimited string.
    • distribution — the main distribution name for Debian-based repos.
    • repo_gpgcheck — set to either true or false to indicate if the repository should validate the repository signature.
    • repo_sourcetype — specifies the source type of the repository path. Supported values are baseurl, metalink, or mirrorlist. With baseurl, the source path is interpreted as a simple URI. If metalink is set, the source path is resolved as a metalink URI, and if mirrorlist is set, the source path is resolved as a mirrorlist file. If not specified, baseurl is the default.
  • --set-repo-credentials=<user:pass_or_filename> — for uri://user:pass@location-type repositories, sets the user and password connected to the set-repo specification. If the provided value describes a filename in the filesystem, the first line of that file is used as credentials.
  • --set-container-derived-from=<uri> — overwrites the source location of the base container for the selected image type. The setting applies only if the configured image type is set up with an initial derived_from reference.
  • --set-container-tag=<name> — overwrites the container tag in the container configuration. The setting is only effective if the container configuration provides the initial tag value.
  • --set-type-attr=<attribute=value> — overwrites/sets the attribute with the provided value in the selected build type section. Example: --set-type-attr volid=some.
  • --set-release-version=<version> — overwrites/sets the release-version element in the selected build type preferences section.
  • --signing-key=<key-file> — sets the key file to be trusted and imported into the package manager's database before performing any operation. This is useful when an image build validates repository and package signatures during build time. This option can be specified multiple times. Trust issues? Not anymore 🔐✨.
  • --target-dir=<directory> — the path to store the build results.

🌈 URI_TYPES 🌈

  • http:// | https:// | ftp:// — a remote repository delivered via the HTTP or FTP protocol.
  • obs:// — an Open Buildservice repository. The source data is translated into an HTTP URL pointing to http://download.opensuse.org.
  • ibs:// — an internal Open Buildservice repository. The source data is translated into an HTTP URL pointing to download.suse.de.
  • dir:// — a local directory.

👑 AUTHOR 👑

Marcus Schäfer. Author icon behavior, honestly.

2020-2026, Marcus Schäfer.

with love from KIWI NG version 11.1.1, dated Oct 06, 2026 — that's the source/version and date, bestie; now go build something iconic 💅✨

📦 where this page comes from