You upgraded Fedora Workstation for years, and now nothing happens
You installed Fedora Silverblue six months ago. The system is stable, your layers are set, and you are comfortable. Then you see Fedora 42 announced. You run sudo dnf upgrade out of habit, and the terminal tells you there is nothing to do. Or you decide you want to try KDE Plasma instead of GNOME, but you do not want to back up your home directory, reinstall, and configure everything from scratch. You are looking for a way to change the base image without losing your work.
The command you need is rpm-ostree rebase. This command swaps the underlying OS image while preserving your user data and layered packages. It is the standard way to upgrade releases, switch desktop environments, or move to a custom build on Fedora Silverblue, Kinoite, and other atomic variants.
What is actually happening
Fedora Workstation uses a mutable root filesystem. You install packages, and dnf merges them into the root tree. Fedora Silverblue uses an immutable, image-based model. The root filesystem is a read-only tree built from a single OCI image. You cannot modify files in /usr directly. Instead, you layer packages on top of the base image, or you swap the entire base image.
Swapping the base image is called rebasing. Think of it like swapping the engine in a car. The chassis, the interior, and the license plates stay the same. The engine changes. Your user data in /home lives on a separate partition or subvolume. It is not part of the base image. Your layered packages live in an overlay filesystem on top of the base. They usually survive the rebase unless they conflict with the new image.
The rpm-ostree tool manages these deployments. It downloads the new image, stages it as a new boot entry, and leaves the current deployment untouched. You reboot to activate the new deployment. If the new image fails to boot, GRUB falls back to the previous deployment automatically. This transactional model makes rebasing safe. You can always roll back if something goes wrong.
Convention aside: rpm-ostree upgrade updates the current image to the latest patch level. rpm-ostree rebase switches to a completely different image. Use upgrade for routine maintenance. Use rebase when you want a new version or a new variant.
Check the current deployment
Before you change anything, verify what is currently running. The rpm-ostree status command shows the active deployment, the staged deployment, and the configured remotes.
rpm-ostree status
# Displays the current boot ID and the deployed image reference.
# Look for the "Deployments" section to see the active root.
# Check the "Version" line to confirm the current release.
The output lists deployments in order. The first deployment is the one currently booted. If you staged a rebase but have not rebooted, the new deployment appears second in the list. The fedora remote is configured by default and points to the official Fedora CDN. You can add custom remotes for third-party images, but the default remote covers all official Fedora releases and variants.
Rebase to a newer Fedora version
To upgrade to a newer Fedora release, rebase to the new image reference. The reference follows the pattern fedora:fedora/<version>/x86_64/<variant>. Replace the version number with the target release. Fedora releases every six months. You can only rebase to versions that have been released. You cannot rebase to a version that is still in development.
rpm-ostree rebase fedora:fedora/42/x86_64/silverblue
# Downloads the new base image from the configured remote.
# This does not modify the current running system.
# It stages a new deployment for the next boot.
The command downloads the image layers. The download size depends on how many layers are already cached. If you rebased from Fedora 40 to 41 recently, the 41 to 42 rebase will reuse many layers and download less data. Once the download completes, the new deployment is staged. The system does not switch until you reboot.
systemctl reboot
# Restarts the system and boots into the staged deployment.
# If the new deployment fails to boot, GRUB falls back to the previous one.
Reboot to activate the new deployment. The staged image does not run until the system restarts.
Switch to a different variant
Switching to a different desktop environment works the same way. Change the variant name in the reference. The official Fedora variants include silverblue for GNOME, kinoite for KDE Plasma, sericea for Sway, and onyx for a minimal GNOME base.
rpm-ostree rebase fedora:fedora/42/x86_64/kinoite
# Targets the Kinoite image instead of Silverblue.
# Layered packages carry over unless they conflict with the new base.
# The new desktop environment packages are part of the base image.
When you switch variants, the new base image includes the packages for the new desktop environment. Your layered packages remain installed. If you layered a package that conflicts with the new base, the rebase will fail. You must remove the conflicting layer before rebasing.
Rebase to a custom OCI image
You can rebase to images hosted on any OCI registry. This is useful for custom builds from UBlue, Bazzite, or your own CI pipeline. The syntax requires the ostree-image-signed:docker:// prefix to tell rpm-ostree to verify the image signature.
rpm-ostree rebase ostree-image-signed:docker://ghcr.io/ublue-os/silverblue-main:42
# Targets an image from GitHub Container Registry.
# The ostree-image-signed prefix enforces signature verification.
# Replace the URL and tag with the desired custom image.
The ostree-image-signed transport ensures the image is cryptographically signed. This prevents tampering. If the registry does not support signature verification, you can use the docker:// prefix, but this is less secure. Only use unsigned transports for images you trust completely.
Verify the result
After the reboot, confirm the system is running the expected image. The rpm-ostree status command shows the new deployment as active.
rpm-ostree status
# Verify the "Deployments" section lists the new version as active.
# Check the "Version" line to ensure it matches the target release.
# Look for the new variant name in the image reference.
You can also check the OS version and kernel with hostnamectl. This command shows the CPE name and the kernel version, which confirms the base image matches the rebase target.
hostnamectl
# Shows the OS version and the CPE name.
# Confirms the kernel and base image match the rebase target.
# Useful for quick verification without parsing rpm-ostree output.
Check the boot journal if the rebase fails. The error message points to the conflicting package or the missing dependency.
Common errors and recovery
Rebasing can fail if the image reference is wrong, if the remote is missing, or if layered packages conflict. The error messages are specific. Read them before forcing anything.
No matching ref
Error: no matching ref "fedora:fedora/99/x86_64/silverblue"
This means the remote does not have that image. Check the version number. Fedora releases are numbered sequentially. You cannot rebase to a version that has not been released yet. Verify the version with rpm-ostree remote refs fedora to see available images.
No such remote
Error: no such remote "fedora"
This means the default remote is missing. Add it back with rpm-ostree remote add. The URL points to the official Fedora CDN.
rpm-ostree remote add fedora https://cdn.fedoraproject.org/ostree/fedora/linux/development/x86_64/silverblue
# Adds the default Fedora remote for Silverblue.
# Use the correct variant path for Kinoite, Sericea, or other spins.
# The remote must exist before you can rebase to its images.
Layered package conflict
Error: transaction test error: package kernel-6.8.0 conflicts with kernel-6.9.0
This usually happens when you have layered a package that clashes with the new base. For example, you might have layered a specific kernel version. The new base expects a different kernel. Uninstall the conflicting layer before rebasing.
rpm-ostree uninstall kernel
# Removes the layered kernel package.
# Allows the rebase to proceed with the base image's kernel.
# Run this before the rebase command to avoid the conflict.
Rollback and cleanup
If the new deployment breaks your hardware or software, roll back to the previous deployment. The system keeps the previous deployment by default.
rpm-ostree rollback
# Marks the previous deployment as the target for the next boot.
# Does not undo layered package changes.
# Reboot to activate the rolled-back deployment.
Rollback restores the previous base image. It does not undo layered package changes. If you installed a package before the rebase, it remains installed after the rollback. Layered packages persist across deployments.
Convention aside: rpm-ostree automatically cleans up old deployments to save disk space. If you want to keep a specific deployment for testing, pin it before cleanup runs.
sudo ostree admin pin 0
# Pins the first deployment in the list.
# Prevents garbage collection from removing this deployment.
# Unpin with `sudo ostree admin unpin 0` when you no longer need it.
Pin the deployment before you clean up. Garbage collection removes unbooted roots.
Decision matrix
Use rpm-ostree rebase when you want to upgrade the entire system to a new Fedora release or switch to a different variant.
Use rpm-ostree upgrade when you want to update to the latest patch level of the current release without changing the base image.
Use rpm-ostree rollback when the current deployment is broken and you need to return to the previous known-good state.
Use rpm-ostree uninstall when a layered package prevents a rebase due to a conflict with the new base image.
Use ostree admin pin when you need to preserve a specific deployment from being garbage collected during cleanup.
Use rpm-ostree remote add when you want to rebase to images from a custom registry that is not configured by default.