You upgraded and the boot stopped at a black screen
You ran dnf upgrade on your main workstation and the boot stopped at a black screen. Or maybe you installed a random RPM from a forum post and now your audio driver is fighting with the kernel. You are staring at a broken system and wondering if Linux is just too fragile for daily use. Fedora Silverblue exists to stop that panic. It changes the rules so a bad update never kills your ability to boot, and a rogue package never corrupts your core system.
The OS is a vinyl record, not a whiteboard
Traditional Fedora Workstation treats your root filesystem like a whiteboard. dnf writes and erases files directly. If the power cuts during a write, or a package dependency resolves wrong, the whiteboard gets smudged. You might not boot. Silverblue treats the OS like a vinyl record. The base image is pressed once and is read-only. You cannot scratch the record.
When an update arrives, the system does not modify the current record. It presses a new one alongside it. You reboot and the bootloader points to the new record. If the new record skips, you point the bootloader back to the old one. The old record is still there, pristine. This is atomic updates. The tool managing this is rpm-ostree. It composes the image, deploys it, and handles the rollback. You do not install packages with dnf on the host. You layer them or use containers.
Update the system and verify the deployment
Here is how you update the OS and verify the new deployment is ready before you reboot.
# Check for new commits in the repository without downloading
rpm-ostree upgrade --check
# Download and deploy the new image to the boot tree
rpm-ostree upgrade
# Reboot to switch to the new deployment
systemctl reboot
rpm-ostree upgrade is the normal weekly maintenance command. It pulls the latest commit from the configured branch and deploys it as a new boot entry. The running system remains unchanged until you reboot. If the reboot fails, the bootloader falls back to the previous deployment automatically.
Reboot to apply the update. The system stays on the old image until the reboot succeeds.
Layer packages for system tools
Sometimes you need a system tool that is not in the base image, like a specific driver or a CLI utility that must run outside a container. Here is how to layer a package on top of the immutable base.
# Layer a package on top of the base image
rpm-ostree install vim-enhanced
# The layer is applied to the next boot tree, not the running system
systemctl reboot
Layered packages are immutable too. You cannot update them with dnf. You must remove and re-add them, or wait for the base image to update. Layering increases the size of the deployment and slows down updates because rpm-ostree must re-compose the image.
Layer sparingly. Every layer increases the image size and slows down updates.
Manage configuration files that survive updates
Config management on Silverblue requires care. Standard edits in /etc work, but a package update might overwrite your changes if the package ships a new default. Here is how to protect a configuration file so it persists across updates.
# Override a config file so it persists across updates
rpm-ostree config override edit /etc/chrony.conf
# The editor opens your local copy, which is protected from package updates
rpm-ostree config override creates a local copy that the system merges. This is safer than editing /etc directly when you want to survive an rpm-ostree upgrade. The override is stored in the deployment metadata and reapplied automatically.
Config files in /etc/ are user-modified. Files in /usr/lib/ ship with the package. Edit /etc/. Never edit /usr/lib/. This holds true for Silverblue too.
Install desktop apps with Flatpak
Desktop applications live in Flatpak. This keeps the GUI ecosystem separate from the OS base. Here is how to add the Flathub remote and install an application.
# Add the Flathub remote if it is missing
flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
# Install an application from the remote
flatpak install flathub org.gimp.GIMP
Flatpak apps run in a sandbox. They have access to your home directory and can request access to specific system resources. The base OS stays clean. You can install hundreds of apps without touching the root filesystem.
Install apps via Flatpak. The base OS stays clean.
Develop in a mutable container
Developers need a mutable environment to compile code and install build dependencies without breaking the host. Here is how to create a Toolbox container and install development tools.
# Create a mutable container with the same user ID as the host
toolbox create
# Enter the container shell
toolbox enter
# Install development tools using the standard package manager
sudo dnf install gcc make cmake
Toolbox containers share the host user and group IDs. Files in ~/ are accessible from both the host and the container. You can edit code in your host editor and run builds inside the container. The container is disposable. If you break it, you delete it and create a new one. The host remains untouched.
Run builds inside Toolbox. The host filesystem remains untouched by your experiments.
Verify the state and recover from errors
Here is how to check the current deployment status and inspect the journal for errors.
# List all deployments and mark the active one
rpm-ostree status
# Check the journal for deployment errors
journalctl -xeu rpm-ostree
rpm-ostree status shows the pinned deployment, the staged deployment, and the rollback target. If the system is stuck, this command tells you which image is active and which one is available for fallback. journalctl -xeu rpm-ostree filters the log to the rpm-ostree unit and adds explanatory text. This is the first place to look when an update fails.
Run rpm-ostree status before you panic. The previous deployment is almost always listed as a fallback.
Common pitfalls and error messages
You will see this error if you try to run dnf install on the host system.
Error: Transaction test error:
file /usr/bin/foo from install of foo-1.0-1.fc40.x86_64 conflicts with file from package ostree-filesystem-2023.1-1.fc40.noarch
The root filesystem is read-only. dnf cannot write to /usr. Use rpm-ostree install for system tools or Toolbox for development packages. Forcing dnf with --skip-broken will not work. The transaction will abort because the filesystem driver rejects writes.
Another common issue is a diverged configuration. If you edit /etc/ directly and then run rpm-ostree upgrade, the package manager might reset the file to the default. You lose your changes. Use rpm-ostree config override to protect critical configs.
Rollback confusion also trips up new users. rpm-ostree rollback swaps the boot order. It does not delete the bad deployment. You can test the rollback, verify the system works, and then switch back to the new deployment if you want to debug. rpm-ostree undo reverts the last transaction entirely. Use rollback to recover quickly. Use undo to clean up.
If the boot menu is gone, GRUB rescue is your friend, not your enemy. Silverblue keeps multiple boot entries. You can select the previous deployment from the GRUB menu even if the automatic fallback fails.
Choose the right Fedora variant
Use Silverblue when you want a known-good base image you can always roll back to. Use Workstation when you need to install kernel modules or low-level driver patches directly on the host. Use Server when you are running services and not a desktop. Stay on the upstream Workstation if you only deviate from the defaults occasionally.