BOOTC-SWITCH(8)

💅 bootc-switch(8) — System Manager's Manual, section 8, bestie edition

okay so picture this: you're deep in the System Manager's Manual (section 8, the big-girl sysadmin section), and you wanna point your whole entire OS at a different container image. that's literally this command. it's bootc-switch and it ate. 🎀

---

✨ NAME ✨

bootc-switch — target a new container image reference to boot 🦋

---

🌸 SYNOPSIS 🌸

bootc switch [OPTIONS...] <TARGET>

---

💖 DESCRIPTION 💖

Target a new container image reference to boot. that's the whole vibe.

This is almost exactly the same operation as upgrade, except — plot twist — it also changes the container image reference. so not just "same image, newer", it's "new image, periodt". 👑

🌈 Usage

a super common pattern: you've got a management agent controlling OS updates through container image tags. for example, quay.io/exampleos/someuser:v1.0 and quay.io/exampleos/someuser:v1.1, where some machines are tracking :v1.0, and as a rollout progresses, machines can be switched to v:1.1. iconic deployment strategy honestly.

it's also supported to hand over explicit digests, like this:

bootc switch quay.io/exampleos/someuser@sha256:9cca0703342e24806a9f64e08c053dca7f2cd90f10529af8ea872afb0a0c77d4

and when you do the digest thing? bootc upgrade will always be a no-op. always. every time. so in that model, upgrades are only ever triggered by further switch operations. you switched, you're locked in, that's the deal. 💀

✨ Applying Changes

the --apply option will automatically restart the system if it has changed after switching to the new image. auto-restart, no extra steps, she's efficient.

🫶 Soft Reboot

for the shared --apply and --soft-reboot behavior, go peek at Soft reboots (see bootc-upgrades(7)). iykyk.

---

🌟 OPTIONS 🌟

• TARGET — the target image to use for the next boot. required, unless --from-downloaded is present. so like, one or the other, bestie, not neither. 🙈
• --quiet — don't display progress. silent mode, mysterious energy.
• --apply — restart or reboot into the new target image. let's gooo.
• --soft-reboot=SOFT_REBOOT — configure soft reboot behavior.
  • possible values:
    • required
    • auto
• --transport=TRANSPORT — the transport; e.g. registry, oci, oci-archive, docker-daemon, containers-storage. defaults to registry.
  • Default: registry
• --download-only — download and stage the update without applying it. prep now, commit later.
• --from-downloaded — apply a staged deployment that was previously downloaded with --download-only. the payoff 🎬
• --enforce-container-sigpolicy — this is the inverse of the previous --target-no-signature-verification (which is now a no-op). so the old one does literally nothing now, noted. ⭐
• --retain — retain reference to the currently booted image. keep the receipts.

---

🎀 EXAMPLES 🎀

Switch to a different image version:

bootc switch quay.io/exampleos/myapp:v1.1

Switch and immediately apply the changes:

bootc switch --apply quay.io/exampleos/myapp:v1.1

Switch with soft reboot if possible:

bootc switch --apply --soft-reboot=auto quay.io/exampleos/myapp:v1.1

---

👑 SEE ALSO 👑

bootc(8), bootc-upgrade(8), bootc-status(8), bootc-rollback(8)

---

⭐ VERSION ⭐

v1.17.1

---

and that's the whole page, bestie 🫶 this was BOOTC-SWITCH(8) from the System Manager's Manual, and for the record it's sitting at version v1.17.1. go switch something, you got this. 💜✨