You upgraded and the boot menu froze
You run sudo dnf upgrade and the terminal reports zero available updates. You check the Fedora release schedule and realize your version just hit end of life. The next step is crossing the major version boundary. You type dnf system-upgrade, but the command hangs or throws a dependency conflict. The screen goes black after a reboot, or the GRUB menu loads into a rescue prompt. A botched major upgrade can leave you staring at a blinking cursor. Run this process from a backup VM first if you can.
What the upgrade process actually does
Fedora releases a new version every six months. The package manager treats major version jumps differently from routine updates. Routine updates replace individual packages while keeping the base system intact. A major upgrade replaces the entire operating system foundation. Think of it like renovating a house while living in it. You cannot swap the foundation and the roof at the same time.
The dnf system-upgrade plugin stages the new packages in a temporary directory, verifies the transaction, and then hands control to a special boot target that applies the changes before the desktop environment loads. Your home directory and configuration files survive the transition. The core binaries and libraries do not. The plugin calculates a complete dependency tree for the target release, downloads every required package, and locks the transaction until you explicitly trigger the reboot. This two-phase approach prevents partial installations from breaking the system.
Preparing the system
Before staging the new release, the current system must be in a clean state. Stale metadata or half-installed packages will poison the upgrade transaction. Run a standard refresh to pull the latest repository indexes. This ensures the dependency solver works with accurate information.
sudo dnf upgrade --refresh
# --refresh forces dnf to ignore cached metadata and fetch fresh repository headers
# This prevents the solver from calculating dependencies against outdated package lists
# A clean baseline reduces the chance of transaction conflicts during the major upgrade
Install the upgrade plugin if your system does not already include it. The plugin ships in the base repositories but sometimes gets omitted on minimal server installs.
sudo dnf install dnf-plugin-system-upgrade
# The plugin adds the system-upgrade subcommand to the dnf binary
# It handles staging, transaction verification, and the special upgrade boot target
# Without it, dnf will refuse to recognize the system-upgrade command
Convention aside: dnf upgrade --refresh is the normal weekly maintenance command. dnf system-upgrade is strictly for crossing major Fedora releases. They use different transaction paths and different repository priorities. Do not mix them in the same command.
Verify that your third-party repositories are compatible with the target release. External sources like RPM Fusion or vendor-specific package sets often ship version-locked packages. Disable them temporarily before staging the upgrade. The solver will fail if an external repository provides a package that conflicts with a core Fedora component.
sudo dnf config-manager --set-disabled rpmfusion-free rpmfusion-nonfree
# Disabling external repos prevents version conflicts during the dependency calculation
# The upgrade plugin only reads enabled repositories when building the transaction
# You can re-enable them after the new release is fully installed
Downloading the new release
The upgrade plugin needs to know which target version to fetch. Fedora does not automatically assume you want the next sequential release. You must specify the target release version explicitly. This prevents accidental jumps across multiple versions or upgrades to testing branches.
sudo dnf system-upgrade download --releasever=41
# --releasever tells the plugin which Fedora version to target for the transaction
# The plugin calculates the full dependency tree for the new release
# Packages are downloaded to /var/lib/dnf/system-upgrade/ instead of being installed immediately
The download phase can take a while depending on your connection speed and how many packages are currently installed. The plugin will pause and ask for confirmation before pulling hundreds of megabytes. Review the transaction summary carefully. It lists packages that will be installed, removed, or downgraded. If the solver stops with a conflict, disable the external repository temporarily and run the download command again.
Error: Transaction test error: package python3-libs-3.12.7-1.fc40.x86_64 conflicts with python3-libs from python3-3.13.0-1.fc41.x86_64
The conflict is intentional. The solver detected that a third-party package pins an older library version. Do not force the transaction with --best or --skip-broken. Those flags bypass safety checks and leave the system in a broken state. Remove the conflicting package or update the external repository to match the target release.
Applying the upgrade
Once the download finishes, verify the staged transaction. The status command shows whether the upgrade is ready to apply or if the download was interrupted.
sudo dnf system-upgrade status
# This command checks the transaction database in /var/lib/dnf/system-upgrade/
# It confirms that all packages downloaded successfully and passed integrity checks
# A clean status output means the system is ready to enter the upgrade boot target
Trigger the reboot. The system will not boot into your usual desktop or console. It drops into a minimal environment that runs the rpm transaction, replaces the core files, and then reboots again.
sudo dnf system-upgrade reboot
# This command modifies the default boot target to systemd-upgrade.service
# The next boot runs the staged rpm transaction in a chroot-like environment
# Do not interrupt the process once the progress bar appears on screen
Convention aside: The upgrade target runs outside your normal user session. It does not load X11, Wayland, or network managers. If you need to monitor progress, watch the serial console or the physical display. The process can take twenty to forty minutes depending on disk speed.
Verifying the transition
After the second reboot, log in and confirm the new version is active. The release file shows the current major version. Run a standard update immediately to synchronize any packages that were deferred during the upgrade transaction.
cat /etc/fedora-release
# This file is updated during the upgrade to reflect the new major version
# It confirms that the boot process completed and the new kernel is active
# A mismatch here indicates the system booted into the old kernel instead
sudo dnf upgrade
# The post-upgrade update resolves deferred dependencies and applies security patches
# It also cleans up any temporary files left behind by the upgrade target
# Running this immediately ensures the system matches the new release repositories
Check the journal for any service failures that occurred during the transition. The upgrade process restarts core services, and some daemons may fail if configuration files changed format.
journalctl -xeu systemd-upgrade.service
# The -x flag adds explanatory text to error messages
# The -e flag jumps to the end of the journal for the most recent entries
# The -u flag filters output to only show the upgrade service unit
Run systemctl status on critical services like NetworkManager, sshd, and firewalld. Services that failed to start usually need a manual restart after configuration schema changes.
sudo systemctl restart NetworkManager firewalld
# Restarting services applies new configuration formats introduced in the target release
# The upgrade transaction replaces binaries but does not automatically restart user daemons
# Verify each service returns an active (running) state before proceeding
Common pitfalls and error messages
Dependency conflicts are the most common failure point. The solver will refuse to proceed if a package from a third-party repository conflicts with a core Fedora package. The terminal prints the exact conflict string. Do not force the transaction. Disable the external repository, run sudo dnf clean all, and retry the download.
SELinux context mismatches appear after major upgrades when new packages introduce files with different security labels. You will see Permission denied errors in application logs or avc: denied messages in the journal. Run sudo restorecon -Rv / to reset contexts to their default values. The -R flag applies recursively and the -v flag prints each fixed file. This step is safe and reversible.
GRUB menu issues happen when the bootloader configuration does not update correctly. If the system boots straight into the old kernel or drops into a rescue shell, check /boot/grub2/grub.cfg. The upgrade process regenerates this file, but custom kernel parameters or encrypted disk setups can interfere. Run sudo grub2-mkconfig -o /boot/grub2/grub.cfg to rebuild the menu. Always verify that your /etc/fstab UUIDs match the actual disk partitions after the reboot. Major version jumps sometimes change default mount options or device naming schemes.
Convention aside: Config files in /etc/ are user-modified. Files in /usr/lib/ ship with the package. Edit /etc/. Never edit /usr/lib/. The upgrade process overwrites /usr/lib/ files on every transaction. Your customizations will vanish.
Check SELinux denials before disabling the security module. The journal logs one-line summaries that explain exactly which process was blocked and why.
setroubleshoot: SELinux is preventing /usr/bin/code from 'read' access on /home/user/.config.
Read the summary. Most denials resolve with a single restorecon or a policy module installation. Disabling SELinux entirely removes a critical defense layer.
When to use system-upgrade versus alternatives
Use dnf system-upgrade when you need to cross a major Fedora release boundary without reinstalling. Use a fresh installation when your system has accumulated years of third-party packages, custom kernel modules, or broken dependency chains. Use dnf upgrade --refresh when you are staying on the same major version and only need security patches and bug fixes. Use rpm-ostree when you are running Fedora Silverblue and need atomic, rollback-capable updates. Stay on the current release if your hardware drivers or specialized software only supports the older kernel version.