You upgraded and the desktop broke
You run rpm-ostree upgrade, wait for the transaction to finish, and reboot. The desktop loads, but your compositor crashes every time you open a window. Or maybe the network manager refuses to connect to your Wi-Fi. You stare at the terminal and wonder if you just bricked your machine. You did not. Fedora Silverblue keeps a complete copy of the previous operating system on disk. You can switch back to it in under a minute. No reinstall. No data loss. No panic.
What is actually happening
Traditional Linux distributions modify the root filesystem in place. dnf downloads packages, extracts them, and overwrites files. If a package breaks, the filesystem is already changed. Silverblue works differently. The operating system is an immutable, read-only tree managed by rpm-ostree. Every upgrade creates a completely new tree. The bootloader simply points to the newest one. The old tree sits on disk, untouched, waiting for you to flip the switch.
Think of it like having two identical hard drives. One runs the current version. The other holds the previous version. Swapping between them takes a single command. Your home directory lives outside this tree. Your documents, downloads, and configuration files in ~/.config survive the switch untouched. The system treats the OS as a single atomic unit. You either boot the new unit or the old unit. There is no half-upgraded state.
This design eliminates dependency hell and broken upgrades. It also changes how you think about configuration. Files in /usr/lib/ ship with the package and cannot be edited. Files in /etc/ are user-modified. Silverblue merges your /etc/ changes into the new tree automatically. If the merge fails, the system falls back to the packaged default and logs a warning. Always edit /etc/. Never edit /usr/lib/.
Check the available deployments before you change anything. The rpm-ostree status command prints a clear inventory of every OS image stored on your system.
Here is how to list the available deployments and identify which one is currently active.
rpm-ostree status
# Shows all deployments on disk, marked with a * for the booted one
# Lists the ostree commit hash, version, and deployment index
# Helps you verify that a fallback image actually exists
The output marks the active deployment with an asterisk. The deployment directly below it is your rollback target. If you see only one entry, the system already garbage-collected the previous version. You cannot roll back in that case.
Run the rollback command to swap the boot order. This command does not modify files. It tells the bootloader to load the previous deployment on the next startup.
Here is how to tell the bootloader to use the previous deployment.
rpm-ostree rollback
# Swaps the default boot entry to the previous deployment
# Does not reboot the system automatically
# Preserves the current deployment for future forward upgrades
Reboot the machine to apply the change. The system will load the older OS image. Your desktop environment, kernel, and system libraries will match the state from before the last upgrade.
Here is how to restart the system and apply the rollback.
sudo systemctl reboot
# Restarts the machine immediately
# Loads the previously selected deployment from disk
# Returns you to the login screen or terminal
Reboot before you debug. Half the time the symptom is gone.
Verify it worked
Log in and run rpm-ostree status again. The asterisk will now sit next to the older deployment. If you are troubleshooting a specific service failure, check the journal to confirm the older version is actually running.
Here is how to verify the active deployment and check recent boot logs.
rpm-ostree status
# Confirms the asterisk moved to the older deployment
# Shows the exact commit hash currently booted
# Verifies the rollback command took effect
Run journalctl -xe if a service still misbehaves. The x flag adds explanatory hints to error lines. The e flag jumps to the end of the log. Most sysadmins type journalctl -xeu <unit> to isolate a single service. Read the actual error before guessing.
Check the merge status if your custom configuration disappeared. Silverblue prints a summary of /etc/ changes during boot. If the older deployment expects a different configuration format, the merge drops the change and logs a warning. You will see a line like Failed to merge /etc/NetworkManager/conf.d/90-defaults.conf in the journal. Restore your configuration manually and test again.
Trust the package manager. Manual file edits drift, snapshots stay.
Common pitfalls and error patterns
Rollbacks are not time machines. They restore the operating system tree and the layered packages that were installed alongside it. They do not restore changes you made to /etc/ configuration files. Silverblue uses a merge system for /etc/. When you roll back, the system attempts to re-apply your local modifications to the older base. If the older base expects a different configuration format, the merge fails silently or drops the change. You will see a warning in the journal if the merge cannot complete.
Layered packages behave differently than dnf packages. When you run rpm-ostree install firefox, the package is baked into the new deployment tree. It does not live in a separate directory. Rolling back removes those layers because they belong to the newer tree. You will need to reinstall them after rolling back. This is intentional. It prevents dependency conflicts between two different OS versions. If you see Error: Transaction test error: package firefox conflicts with base image, the system is protecting you from mixing incompatible layers.
If the system fails to boot after an upgrade, you do not need a terminal. The GRUB menu retains a fallback entry for the previous deployment. Press e to edit the boot parameters if you need to drop to a root shell, or simply select the older entry and press Enter. The entry usually displays the previous Fedora version and the commit date. If you see error: unknown filesystem or failed to load linux, your bootloader configuration might be out of sync. Run sudo rpm-ostree initramfs -- regenerate from a live USB or recovery environment to fix it.
Garbage collection removes old deployments to save disk space. Silverblue keeps a maximum of two deployments by default. If you upgrade three times in a row, the oldest image gets deleted. You cannot roll back past the immediately previous version unless you pinned it. Pinning is useful when you are testing a new release and want a guaranteed escape hatch.
Here is how to pin a deployment so the system never deletes it.
sudo ostree admin pin 1
# Marks deployment index 1 as permanent
# Prevents automatic garbage collection
# Keeps the image on disk until you manually unpin it
Use sudo ostree admin pin --unpin 1 to release the disk space later. Check rpm-ostree status to see which index corresponds to which version. The index resets after a reboot, so always verify the number before pinning.
SELinux denials show up in journalctl -t setroubleshoot with a one-line summary. Read those before disabling SELinux. A rollback will not fix a policy mismatch. You need to adjust the context or file label.
Run journalctl first. Read the actual error before guessing.
When to use this versus alternatives
Use rpm-ostree rollback when the system boots but a desktop component or system service fails. Use the GRUB fallback menu when the system drops to a kernel panic or fails to reach the login screen. Use ostree admin pin when you are testing a major release upgrade and need a guaranteed safe state. Use rpm-ostree upgrade when you want to return to the newer deployment after confirming the rollback fixed the issue. Stay on the current deployment when the problem is isolated to a user application or a misconfigured service in /etc/.
Snapshot the system before the upgrade. Future-you will thank you.