KIWI::SYSTEM::STACKBUILD(8)

💅 KIWI::SYSTEM::STACKBUILD 💅

okay so bestie, welcome to kiwi::system::stackbuild (that's the KIWI::SYSTEM::STACKBUILD(8) page, section 8, we're fancy) — the command that builds an image on top of stash containers. yes, the name is long. no, we're not changing it. sit down, grab a 🍓, let's go.

---

✨ NAME ✨

kiwi::system::stackbuild — build an image based on stash containers. that's it, that's the whole vibe. 🎀

---

🦋 SYNOPSIS 🦋

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

kiwi-ng system stackbuild --help
kiwi-ng system stackbuild --stash=<name>... --description=<directory> --target-dir=<directory>
    [--from-registry=<URI>]
    [kiwi <kiwi_build_command_args>...]
kiwi-ng system stackbuild --stash=<name>... --target-dir=<directory>
    [--from-registry=<URI>]
    [kiwi <kiwi_create_command_args>...]

like, copy those exact lines, they're not decorative. ✨

---

🌸 DESCRIPTION 🌸

so the whole point: you build an image based on one or more stash containers. a stash is a root tree that KIWI NG built and then stored as an OCI container — peep kiwi-ng system stash if you wanna know more. and the reason OCI images are the moment here is that they're the portable format for storing AND distributing a root tree, which means you can push them to and pull them from OCI registries. iconic behavior, truly. 👑

the stackbuild command has two modes and honestly both ate:

1. 🔁 Rebuild an image from a stash

in this mode, stackbuild takes a stash, makes it available to the local registry, and then builds the image using the stash rootfs and the image description that's stored inside the stash. the kiwi subcommand arguments you hand over get passed straight along to the kiwi-ng system create command.

$ kiwi-ng system stackbuild --stash NAME \
    --target-dir /target/rebuild

2. 🧱 Build an image based on a stash

in this mode, stackbuild takes a stash, makes it available to the local registry, and then uses the stash rootfs as the base for building another image description. the kiwi subcommand arguments you give get passed along to the kiwi-ng system build command. main character energy honestly.

$ kiwi-ng system stackbuild --stash NAME \
    --description /some/image-description \
    --target-dir /target/rebuild

NOTE: bestie. listen. the stackbuild command does not do any consistency check to figure out whether the stash rootfs you're using is actually compatible with the image description you provided. so like… nothing is stopping you from grabbing a Leap stash and trying to build a Fedora image on top of it. 😭 it's on you, the user, to only combine stashes and image descriptions that are compatible. it is the user's responsibility. no cap.

for a detailed introduction, see Building based on Containers. 🫶

---

💅 OPTIONS 💅

• --stash=<name> — the name of the stash. run kiwi-ng system stash --list to see what stashes you actually have available. and yes, you can pass multiple stashes — they get stacked together in the order you give them. order matters, iykyk. 🎀
• --from-registry=<URI> — pull that stash container name from the registry URI you provide. easy.
• --description=<directory> — path to the XML description. it's a directory containing at least one config.xml or *.kiwi XML file.
• --target-dir=<directory> — path where the build results get stored. your output lives here ✨
• kiwi <kiwi_build_command_args>... — a list of command parameters as supported by the kiwi-ng system build command. everything you put here gets passed along to kiwi-ng system build if the --description option is set. 👀
• kiwi <kiwi_create_command_args>... — a list of command parameters as supported by the kiwi-ng system create command. everything you put here gets passed along to kiwi-ng system create if the --description option is not set. 💅

NOTE: for compatibility with the former kiwi-stackbuild-plugin, the -- separator is accepted as an alias for the kiwi subcommand. legacy icon behavior, we respect it. 🙈

---

🌈 EXAMPLE 🌈

$ kiwi-ng system stackbuild --stash NAME --target-dir /target/rebuild \
    kiwi --signing-key /path/to/key

look at that. chefs kiss. 🔥

---

👑 AUTHOR 👑

Marcus Schäfer. legend. 💜

---

⭐ COPYRIGHT ⭐

2020-2026, Marcus Schäfer

---

and that's the page, bestie! this was KIWI::SYSTEM::STACKBUILD(8) from KIWI NG, version 11.1.1, dated Oct 06, 2026 — go forth, stack those stashes, and remember to vibe check your compatibility yourself because the command literally will not do it for you 💖🌸🧚