rpm-ostree: rebase, pin, rollback

#linux #bazzite #immutable-os #rpm-ostree #fedora

Cheat-sheet for moving between OS images on rpm-ostree systems. What each verb actually does and how not to lose access to a working boot.

rpm-ostree manages the OS image on Fedora's atomic desktops (Silverblue, Kinoite, Bazzite). A handful of verbs cover 90% of what you need.

# The shape

You always have two deployments at minimum: the one you're running and the one you'll roll back to. Each rpm-ostree operation stages a new deployment. Nothing changes until you reboot.

$ rpm-ostree status -v
State: idle
Deployments:
* ostree-image-signed:docker://ghcr.io/ublue-os/bazzite:stable
                   Digest: sha256:…
                  Version: 41.20260420.0   (current)
  ostree-image-signed:docker://ghcr.io/ublue-os/bazzite:stable
                   Digest: sha256:…
                  Version: 41.20260413.0   (rollback target)

* marks "currently booted". Reboot into the older deployment from GRUB to roll back.

# Verbs

  • rpm-ostree upgrade. Fetch the latest ref of the same image. Reboot to apply.
  • rpm-ostree rollback. Make the previous deployment the default for next boot.
  • rpm-ostree rebase ostree-image-signed:docker://ghcr.io/<org>/<image>:<tag>. Switch to a different OS image. How you go between Bazzite GNOME and Bazzite KDE, between :stable and :testing, or to a uBlue variant.
  • rpm-ostree deploy <version>. Pin to a specific image version. Subsequent upgrade calls won't move past it until you deploy --reset.
  • rpm-ostree reset. Drop all layered packages and overrides. Useful when an upgrade is wedged because of a layering conflict.

# Pin a known-good deployment

Pin the current deployment so a future rollback can reach it:

sudo ostree admin pin 0

Pinned deployments aren't garbage-collected when newer ones land. List with ostree admin status. Unpin via ostree admin pin --unpin <index>.

# Layering escape hatches

You can install RPMs into the image with rpm-ostree install <pkg>. They become layers on top of the base. Keep this list short:

  • Every layer has to be re-applied on each rebase, slowing rebase and upgrade.
  • A package that conflicts with the new base wedges the upgrade until you rpm-ostree override remove or rpm-ostree reset.
  • Layered drivers and kernel modules are particularly fragile across major version jumps.

# When a boot fails

GRUB shows the previous deployment as a separate entry. Reboot, pick one. The next rpm-ostree status will show the broken one as "Deployment 1". rpm-ostree rollback makes it the default; rpm-ostree cleanup -p drops it once you've recovered.

# References