---
title: "rpm-ostree: rebase, pin, rollback"
date: 2026-04-25
tags: [linux, bazzite, immutable-os, rpm-ostree, fedora]
summary: 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.
aliases: [rpm-ostree-rebase-cheatsheet, rpm-ostree-cheatsheet]
---

`rpm-ostree` manages the OS image on Fedora's atomic desktops ([Silverblue](https://fedoraproject.org/atomic-desktops/silverblue/), [Kinoite](https://fedoraproject.org/atomic-desktops/kinoite/), [[bazzite-overview|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](https://universal-blue.org/) 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:

```bash
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.

## Related

- [[bazzite-overview]]. Context for why this is even a thing.
- [[flatpak-1password-browser-bridge]]. Flatpak troubleshooting for sandbox-aware apps.

## References

- [rpm-ostree user manual](https://coreos.github.io/rpm-ostree/)
- [Fedora image-based updates](https://docs.fedoraproject.org/en-US/fedora-silverblue/updates/)