How to Upgrade Fedora Silverblue to the Next Version
You see the notification that Fedora 41 has shipped. Your laptop is running Fedora 40 Silverblue. You want the new kernel, the updated GNOME stack, and the latest security patches. You open the terminal and type dnf upgrade, expecting the familiar progress bar. Instead, the terminal spits out Error: Transaction is read-only and refuses to do anything. Or you try rpm-ostree upgrade and worry that a single typo will leave you without a bootable system.
The upgrade path on Silverblue is different from Workstation. It does not modify files in place. It fetches a new system image, verifies its integrity, and prepares a new boot entry. The reboot swaps the boot entry. If the new image fails, the bootloader falls back to the previous version automatically. The process is atomic and safe, but it requires the right commands.
What's actually happening
Silverblue uses OSTree to manage the operating system tree. OSTree treats the system as a collection of immutable commits. Each commit is a complete snapshot of the filesystem, identified by a cryptographic hash. When you upgrade, you are not patching individual files. You are downloading a new commit that represents the target release.
Think of the system like a digital vinyl record. You do not scratch new grooves into the existing disc. You press a whole new disc with the updated tracks and swap it in. The old disc stays on the shelf until you decide to remove it. This design ensures that the running system is never corrupted by a partial update. It also enables instant rollbacks. The bootloader maintains a list of deployments. If the current deployment fails to boot, the bootloader tries the previous one.
The rpm-ostree command orchestrates this process. It contacts the configured repositories, resolves the latest commit, downloads only the layers that have changed, verifies the GPG signature, and updates the bootloader configuration. The currently running filesystem remains untouched until you reboot.
Convention aside: rpm-ostree is the package manager for the base OS on Silverblue. dnf is still available, but it operates in a restricted mode. Use dnf to install user-space applications or layer packages that are not part of the base image. Use rpm-ostree for system upgrades, kernel changes, and managing the immutable tree. Mixing the two without understanding the boundary leads to confusion.
Preparing for the upgrade
Check disk space before starting. OSTree downloads the new tree structure, which can be several gigabytes even if only a few packages changed. A full disk will abort the transaction and leave the system in a degraded state.
df -h /
# Shows available space on the root filesystem.
# Ensure at least 4 GB of free space to accommodate the new tree and temporary files.
# OSTree requires space for the new deployment alongside the current one.
Review your layered packages. If you have installed additional packages using rpm-ostree install, those layers are applied on top of the base image. A major release upgrade might introduce conflicts if a layered package depends on a library version that has changed. Reviewing layers beforehand allows you to remove unnecessary packages and reduce the risk of conflicts.
rpm-ostree status
# Displays the current deployment and any layered packages.
# Look for the "Layered packages" section.
# Identify packages that are no longer needed or might conflict with the new release.
Remove obsolete layers to keep the system clean. This reduces the attack surface and prevents dependency resolution errors during the upgrade.
rpm-ostree uninstall <package-name>
# Removes the specified package from the layer.
# Prepares a new deployment without the package.
# Reboot is required to apply the removal.
Check disk space before downloading. A full disk aborts the transaction and wastes bandwidth.
The upgrade process
Run rpm-ostree upgrade to fetch and apply the next version. This command updates the system image to the latest release available in your configured repositories. It does not modify the running system. It prepares the new deployment for the next boot.
rpm-ostree upgrade
# Fetches the latest commit from the configured repository.
# Verifies the GPG signature against the trusted keyring.
# Downloads only the layers that have changed since your current version.
# Prepares a new boot entry in the bootloader configuration.
# Does not modify the currently running filesystem.
The command outputs the commit hash of the new deployment and lists the packages that will be updated, added, or removed. Review this output to confirm the changes match your expectations. If the output looks correct, proceed to reboot.
Reboot the system to activate the new deployment. The bootloader will switch to the new entry automatically. If the new image fails to boot, the bootloader falls back to the previous deployment on the next attempt.
systemctl reboot
# Restarts the system and applies the new boot entry.
# The bootloader attempts the new image first.
# If the new image fails, the fallback entry activates automatically.
# No manual intervention is required for standard failures.
Review your layers before upgrading. Conflicts are easier to resolve before the new tree arrives.
Verifying the upgrade
After the system boots, verify that the upgrade succeeded. Check the version number and the commit hash to confirm you are running the expected deployment.
rpm-ostree status
# Displays the current deployment and available rollback options.
# Confirms the version number matches the target release.
# Shows the commit hash for auditability.
# Lists the pinned state and any layered packages.
The output should show the new version under the Deployments section. The * marker indicates the currently booted deployment. If the version is correct and the system is stable, the upgrade is complete.
Update your Flatpak applications. The base OS upgrade does not automatically update Flatpaks. Run the Flatpak update command to ensure your applications are in sync with the new runtime libraries.
flatpak update
# Fetches updates for all installed Flatpak applications.
# Downloads new runtimes if required by the updated applications.
# Ensures applications are compatible with the new system libraries.
Run rpm-ostree status immediately after reboot. Verify the version and commit hash before assuming success.
Common pitfalls and errors
The dnf upgrade command fails with Error: Transaction is read-only. This error occurs because Silverblue mounts the root filesystem as read-only. dnf attempts to modify files directly, which the filesystem rejects. Use rpm-ostree upgrade for system updates. Use dnf only for layering packages or managing user-space software that does not touch the base tree.
The upgrade fails with Error: No such commit .... This error indicates that rpm-ostree cannot find the target commit in the configured repositories. Check your repository configuration. Ensure the repository URL is correct and the repository is enabled. If you are using a custom repository, verify that the repository contains the commit for the target release.
rpm-ostree config list
# Lists all configured repositories and their states.
# Check for repositories that are disabled or have incorrect URLs.
# Verify that the repository containing the target release is enabled.
The upgrade fails with Error: Insufficient disk space. This error occurs when the disk does not have enough free space to download and store the new deployment. Free up space by removing old deployments or cleaning the OSTree cache.
rpm-ostree cleanup --reporepack
# Removes old deployments that are no longer needed.
# Repacks the OSTree repository to reclaim space.
# Frees disk space for future upgrades.
The system fails to boot after the upgrade. Silverblue includes a built-in rollback mechanism. If the new deployment fails, the bootloader automatically attempts the previous deployment on the next boot. If the fallback also fails, boot from a USB installer and use the recovery shell to repair the bootloader configuration. Do not panic. The immutable design protects your data.
Trust the bootloader fallback. If the new image fails, the previous deployment boots automatically on the next attempt.
When to use this vs alternatives
Use rpm-ostree upgrade when you want to move to the next minor or major release defined by your repository configuration. Use rpm-ostree rebase when you need to switch to a specific commit hash or a different repository branch, such as moving from Stable to Testing. Use dnf system-upgrade when you are on Fedora Workstation and need to upgrade the mutable package database. Use a clean installation when your current deployment has accumulated too many custom layers or configuration drift to manage safely.
Use rpm-ostree upgrade for standard releases. Use rebase for specific commits or branch switches.