The upgrade scenario
You are sitting at your desk. Fedora 40 is running fine. Fedora 41 just dropped. You want the new kernel, the updated desktop, and the security patches without wiping your home directory or reinstalling your dotfiles. You open a terminal and type dnf system-upgrade. The process downloads gigabytes of packages, reboots, and hands you back a fresh system. Sometimes it works silently. Sometimes it stops at a black screen with a dependency conflict. This guide covers the exact sequence that keeps your system intact and your data safe.
Stage the download before you reboot. A failed transaction is easier to fix when the running system is untouched.
What in-place upgrades actually do
In-place upgrades do not copy your files to a new partition. They replace the packages currently installed on your root filesystem with the newer versions from the target release repository. Think of it like swapping out the engine and transmission in a running car while keeping the chassis, interior, and driver seat exactly where they are. The package manager calculates a transaction that removes old packages, installs new ones, and migrates configuration files. Your home directory, /etc customizations, and third-party repositories remain untouched. The bootloader gets updated to point to the new kernel. If the transaction fails mid-way, the system rolls back to the last known good state. That rollback is why you must run the download phase first. It stages everything before touching the running system.
Fedora ships every six months. The N-2 release reaches end of life when N+1 arrives. You cannot jump from an EOL release directly to the current one using the standard upgrade path. You must step through each active release in sequence. Plan your upgrades around that six-month cadence.
The upgrade environment lives inside the initramfs. When you reboot after staging the transaction, the bootloader loads a modified initramfs that contains the system-upgrade plugin. That plugin intercepts the normal boot sequence, mounts your root filesystem read-only, and applies the downloaded RPMs in a controlled transaction. Once the packages are installed, the system reboots again with the new kernel. This two-phase approach prevents partial installations from corrupting your running environment.
Stage the download before you reboot. A failed transaction is easier to fix when the running system is untouched.
Running the upgrade
Refresh the metadata and apply all pending updates for your current release. This ensures the package manager has the latest repository information and resolves any partial transactions before the major version change.
sudo dnf upgrade --refresh
# --refresh forces dnf to ignore cached metadata and fetch fresh repo data
# This prevents dependency resolution failures caused by stale repository mirrors
# Running a full upgrade first clears out half-installed packages from previous sessions
Stage the upgrade transaction. The system-upgrade plugin downloads every package required for the target release and stores it in the dnf cache. It does not install anything yet. This separation is intentional. If the download fails or a repository is unreachable, your running system remains completely untouched.
sudo dnf system-upgrade download --releasever=41
# --releasever tells dnf which Fedora release repository to target
# Omitting this flag defaults to the next sequential release number
# The plugin calculates the full transaction and downloads all RPMs to /var/cache/dnf
# If you skip this step, the reboot phase will fail immediately
Verify the staged transaction before rebooting. The status command confirms that the download completed successfully and that the upgrade payload is ready to apply.
sudo dnf system-upgrade status
# This command checks the dnf cache for a valid upgrade transaction
# A "Ready for upgrade" message means all packages downloaded without corruption
# An empty or error output indicates a failed download or interrupted session
Reboot the system. The bootloader detects the staged transaction and switches to a special upgrade environment before mounting your root filesystem normally. The system applies the new packages, updates GRUB, and reboots again automatically.
sudo reboot
# The initramfs contains the system-upgrade plugin that intercepts the boot process
# Package installation happens in a chroot-like environment to protect running services
# Do not interrupt power during this phase. The rollback mechanism only triggers on clean failures.
dnf upgrade --refresh is your weekly maintenance command. dnf system-upgrade is strictly for crossing major release boundaries. They share the same package manager backend but use completely different transaction flags. Do not mix them.
Watch the terminal output during the reboot phase. The upgrade environment prints progress directly to the console.
Verifying the new release
Log in and confirm the kernel and release version. Run a distribution sync to align any packages that might have been held back or partially configured during the transition.
cat /etc/fedora-release
# Confirms the OS release string matches your target version
uname -r
# Verifies the running kernel matches the new release tree
sudo dnf distro-sync
# Aligns all installed packages with the default versions in the target release
# Resolves any architecture or dependency drift that occurred during the swap
sudo dnf clean all
# Purges the old upgrade cache and stale repository metadata
# Frees several gigabytes of disk space left over from the download phase
Run distro-sync immediately after login. Package drift compounds quickly if left unchecked.
Common failure modes and how to read them
Third-party repositories are the most common cause of upgrade failures. RPM Fusion, Flatpak remotes, or custom Docker repositories often ship packages that conflict with core Fedora components. The transaction will abort and print a dependency conflict.
Error: Transaction test error:
package kernel-core-6.8.0-1.foo.x86_64 conflicts with kernel-core provided by kernel-core-6.7.0-1.bar.x86_64
The conflict is intentional. Fedora protects its core packages from external overrides. Disable third-party repositories before running the download phase. Re-enable them after the upgrade completes.
Configuration file conflicts appear when a package ships a modified default configuration that clashes with your local edits. The package manager will pause and ask whether to keep your version or install the vendor default.
configuration file /etc/sysctl.d/99-sysctl.conf:
install: keep the .rpmnew file
install: keep the .rpmsave file
install: install the vendor version
Choose the vendor version only if you understand the changes. Otherwise, keep your local file and manually merge the new settings. The .rpmnew suffix marks the untouched vendor default. The .rpmsave suffix marks your old configuration.
SELinux context mismatches occasionally surface after a major version jump. File permissions and security labels sometimes drift when packages move between directories. Check the audit log before disabling the security module.
sudo journalctl -t setroubleshoot --since "1 hour ago"
# The setroubleshoot service translates raw AVC denials into human-readable warnings
# Read the one-line summary to identify which service is being blocked
# Disabling SELinux globally masks the symptom and leaves the system exposed
If the boot menu disappears or the system drops to a rescue shell, your GRUB configuration likely failed to update. The upgrade environment sometimes misses custom kernel parameters. Boot into the previous kernel entry from the GRUB menu, then regenerate the bootloader configuration.
sudo grub2-mkconfig -o /boot/grub2/grub.cfg
# Scans /boot for available kernels and rebuilds the GRUB menu structure
# Always run this after a manual kernel installation or a failed upgrade
# The output confirms which kernel entries were detected and added
Config files in /etc/ are yours to modify. Files in /usr/lib/ ship with the package and get overwritten on every update. Edit /etc/. Never edit /usr/lib/. The same rule applies to systemd unit files. Override units live in /etc/systemd/system/. Package units live in /usr/lib/systemd/system/.
Check the logs before you guess. journalctl tells you exactly which package or service broke the chain.
Choosing your upgrade path
Use dnf system-upgrade when you want to preserve your local configuration, installed applications, and user data while moving to the next active release. Use a fresh installation when your current system carries years of package drift, broken third-party repositories, or corrupted bootloader entries. Use Fedora Silverblue when you want an immutable base image that rolls back automatically on failed updates. Use Fedora Kinoite when you need a desktop environment that matches the immutable upgrade model but prefers KDE Plasma. Stay on the standard Workstation edition if you only deviate from the defaults occasionally and want full control over package versions.
Pick the path that matches your tolerance for manual intervention. Clean installs are faster. In-place upgrades are safer for complex setups.