Upgrade Fedora Linux with DNF System-Upgrade Command

On Fedora 41 and newer releases, the dnf command now uses DNF5, the next-generation package manager that delivers faster dependency resolution and smoother upgrades. The dnf5 system-upgrade command automates in-place upgrades, handling package downloads, dependency resolution, and installation during a system reboot. This guide walks you through upgrading your Fedora system confidently, with step-by-step instructions and practical troubleshooting tips to ensure a smooth transition to the latest release.

You will prepare your workstation with full backups, repository health checks, and release notes, then install the dnf5-plugin-system-upgrade package, download the next release with the right flags, and reboot into Fedora’s offline installer. The final sections cover verification, cleanup, and troubleshooting commands so you can recover quickly if disk space, dependency conflicts, or boot issues arise.

What Is the dnf5 system-upgrade Command?

How the Plugin Handles Upgrades

The dnf system-upgrade plugin has long been Fedora’s preferred way to move between releases. With Fedora 41 and newer, the plugin runs on top of DNF5 by default, so you will often see it described as the dnf5 system-upgrade command. It automates the download and installation of necessary packages and applies changes during a system reboot in an offline environment.

This plugin allows users to transition smoothly to a newer Fedora release without needing to reinstall the operating system manually. It handles complex tasks like dependency resolution, package replacements, and kernel upgrades. By default, it behaves like distro-sync, meaning it will synchronize all packages to match the new release repositories. This can include downgrading certain packages to their new release versions if needed, which ensures your system perfectly matches the target release.

Respect Fedora’s Sequential Upgrade Policy

Fedora only supports moving up one release at a time, so confirm the next version is available and fully synced before downloading packages.

Fedora only supports sequential upgrades. For example, if you were running Fedora 43, you would need to upgrade to Fedora 44 before moving to Fedora 45. Attempting to skip releases (like jumping from Fedora 43 directly to Fedora 45) is not supported and will likely cause package conflicts or system instability.

Key Benefits

• Efficient Process: Automatically downloads and installs all required updates for the target Fedora release.
• Reduced Risks: Handles potential conflicts by providing options like --allowerasing to resolve package issues during the upgrade.
• User-Friendly: Needs very little hands-on work, making it accessible for both new and experienced users.

The dnf system-upgrade plugin is an essential tool for Fedora 41 and onwards users who want to keep their systems updated with the latest features, performance improvements, and security patches. Using the dnf5 system-upgrade command ensures your system stays current with minimal effort.

Review Release Notes and DNF Version Differences

Crucially, before proceeding, always review the official Fedora release notes for the specific version you are upgrading to. These notes contain vital information about significant changes, potential issues, and deprecated features that could impact your system. Visit Fedora’s official documentation for the latest release notes. For automated security updates between major upgrades, consider setting up dnf-automatic to keep your system patched.

If you are running an older Fedora release (such as Fedora 39 or Fedora 40 from previous years), you might still see references to the legacy DNF4 and the standalone dnf5 binary. The commands in this guide use dnf, which maps to DNF5 on Fedora 41+ systems. The same syntax works on those older releases as long as the DNF5 packages are installed, or you can swap dnf for dnf5 if needed.

Command Syntax Breakdown

If you are new to dnf system-upgrade, understanding the basic syntax helps you use it effectively. The command follows this structure:

sudo dnf system-upgrade <subcommand> [options]

• dnf system-upgrade: The main command that invokes the system upgrade plugin
• subcommand: Specifies the action (download, reboot, clean, or log)
• options: Additional flags that modify behavior (such as --releasever, --allowerasing, or --no-downgrade)

At its simplest, upgrading to the next Fedora release requires just two commands: sudo dnf system-upgrade download --releasever=<version> to fetch packages, then sudo dnf system-upgrade reboot to apply them during an offline upgrade. For example, if you’re running Fedora 44 and want to upgrade to Fedora 45, you’d use --releasever=45.

Available Subcommands

The dnf system-upgrade plugin provides several subcommands to manage the upgrade process:

• download: Downloads all packages needed to upgrade to a new release and verifies they can be installed
• reboot: Triggers a system reboot into the offline upgrade environment to apply the downloaded packages
• clean: Removes downloaded upgrade data to free up disk space after a successful or failed upgrade
• log: Displays logs from previous upgrade attempts for troubleshooting and verification

These subcommands give you complete control over the upgrade process, from preparation through completion and cleanup.

Common Options Reference

The table below organizes key options by task to help you quickly find the right flags for your upgrade scenario:

Task	Options	What They Do
Specify target version	--releasever=<version>	Sets the Fedora version to upgrade to (e.g., 45, 46)
Prevent package downgrades	--no-downgrade	Only installs newer packages, skips packages that would downgrade
Resolve package conflicts	--allowerasing	Allows removing conflicting packages to complete the upgrade
View upgrade logs	--number=-1	Shows logs from the most recent upgrade attempt
Power off instead of reboot	--poweroff	Shuts down the system after preparing for upgrade

You can combine options when needed. For example, sudo dnf system-upgrade download --releasever=<version> --no-downgrade --allowerasing fetches packages for the target Fedora release while preventing downgrades and allowing package removal to resolve conflicts.

Pre-Upgrade Preparation

Preparation is essential to ensure a smooth and successful system upgrade. Follow these steps to ready your system:

Update Your Current System

Before starting the upgrade, make sure your system is fully up-to-date. This minimizes potential conflicts and ensures a stable starting point for the upgrade process. Run the following command to update all installed packages:

sudo dnf --refresh upgrade

This command refreshes repository metadata and installs the latest versions of all available updates for your current Fedora release. If you want to increase DNF speed for faster downloads, consider optimizing your DNF configuration.

Back Up Important Data

System upgrades carry inherent risks, so it’s crucial to back up any important files or configurations. Use an external storage device or a reliable cloud service to safeguard your data. This precaution ensures you can recover your information in case of an unexpected issue during the upgrade.

Check System Requirements

Ensure your system meets the following requirements for a successful upgrade:

• Stable Internet Connection: Upgrading requires downloading several packages, so a reliable connection is essential.
• Sufficient Disk Space: Verify that your system has enough free space to accommodate the new packages. Use the command below to check disk usage:

df -h

If disk space is low, delete unnecessary files or transfer large files to external storage. Ensure your system has a stable power supply during the upgrade. If you are using a laptop, keep the charger connected throughout the process.

Disable Third-Party Repositories

Third-party repositories can sometimes cause conflicts during upgrades. Temporarily disable them with this command:

sudo dnf config-manager setopt <repository_name>.enabled=0

After the upgrade is complete, you can re-enable these repositories to restore additional functionality.

Review Fedora Release Notes

Before proceeding, review the release notes for the Fedora version you’re upgrading to. Release notes provide critical information about new features, deprecated packages, and potential compatibility issues that might impact your setup. Visit Fedora’s official documentation for the latest release notes.

How to Use the dnf5 system-upgrade Command

The dnf5 system-upgrade plugin simplifies upgrading Fedora by automating package downloads and applying the upgrade during a system reboot. Follow these steps to upgrade your Fedora system safely and efficiently:

Step 1: Install the System Upgrade Plugin

First, ensure the dnf5-plugin-system-upgrade package is installed. This plugin is typically pre-installed on Fedora 41 and later systems.

Check its status with:

rpm -q dnf5-plugin-system-upgrade

If the package is missing, install it with the following command to guarantee the plugin is available:

sudo dnf install dnf5-plugin-system-upgrade

This command ensures the required plugin is available for managing the system upgrade process. For more examples of installing packages with dnf5, see our DNF5 install guide.

Step 2: Download Upgrade Packages

Next, download all the necessary packages for the target Fedora release. Replace <target_version> with the Fedora version number you wish to upgrade to (e.g., 45):

sudo dnf system-upgrade download --releasever=<target_version>

By default, system-upgrade behaves like distro-sync, synchronizing all packages to match the new release, even if that means installing older versions from the new repositories. This default behavior is what most users want, as it ensures complete compatibility with the target release. If you prefer traditional upgrade behavior that only installs newer packages, add the --no-downgrade flag:

sudo dnf system-upgrade download --releasever=<target_version> --no-downgrade

If package conflicts occur, try the --allowerasing option. This flag lets DNF5 remove or replace conflicting packages so the transaction can continue. It often clears stubborn dependency loops, but review the removal list carefully because it can still take out packages you depend on. If something critical would be erased, handle that package manually before rerunning the upgrade:

sudo dnf system-upgrade download --releasever=<target_version> --allowerasing

You can combine options as needed. For example, to prevent downgrades while allowing package removal:

sudo dnf system-upgrade download --releasever=<target_version> --no-downgrade --allowerasing

Step 3: Reboot and Apply the Upgrade

After successfully downloading the upgrade packages, reboot your system to initiate the upgrade:

sudo dnf system-upgrade reboot

Alternatively, if you prefer to power off instead of rebooting (for example, to perform hardware changes or schedule the upgrade for later), use:

sudo dnf system-upgrade reboot --poweroff

During the reboot, your system will boot into a special offline upgrade environment (using systemd’s offline-updates mechanism) where it applies the downloaded packages. You’ll typically see a progress bar or status messages on a dark screen. This offline process finalizes the upgrade and can take some time depending on your system and the number of updates. Do not interrupt it. For laptops, keep the charger connected throughout the entire upgrade to avoid power interruptions.

Stick with sudo dnf system-upgrade reboot for release upgrades. Other offline reboot triggers, such as dnf offline reboot, handle regular updates and won’t apply the staged system-upgrade transaction.

Post-Upgrade Steps

After completing the upgrade, it’s essential to verify the system, re-enable any previously disabled repositories, and clean up leftover files. Follow these steps to finalize the process:

Verify the Upgrade

Start by confirming that your system is running the upgraded Fedora version. Use the following command to check the current release:

cat /etc/os-release

This command displays the Fedora version and release information. If the version doesn’t match your target release, review the upgrade logs to identify any issues:

sudo dnf system-upgrade log --number=-1

This command shows the logs from your most recent upgrade attempt, which can help diagnose problems. For advanced troubleshooting or unique issues, consult the official Fedora documentation for the most up-to-date guidance.

Re-enable Disabled Repositories

If you disabled third-party or custom repositories during the upgrade, re-enable them to restore full system functionality:

sudo dnf config-manager setopt <repository_name>.enabled=1

DNF5 removed the legacy --enable and --disable flags, so use the unified setopt <repository>.enabled=1 syntax whenever you need to toggle repositories.

Clean Up the System

To ensure optimal performance and free up disk space, remove unused or obsolete packages and clear cached files:

• Remove unnecessary packages:

sudo dnf autoremove

• Clean up system-upgrade specific data:

sudo dnf system-upgrade clean

• Clean up all cached files:

sudo dnf clean all

The system-upgrade clean command specifically removes downloaded upgrade packages and metadata, while clean all removes all cached package files and temporary data, helping to free up significant disk space and maintain a tidy system.

Test Your Applications

Run your critical applications to verify that they work as expected. Pay special attention to any software with dependencies that may have been updated during the upgrade. If issues arise, consider reinstalling the affected application or checking the Fedora documentation for compatibility updates.

If you use custom configurations or third-party software, check their compatibility with the new Fedora release to avoid disruptions in your workflow.

Troubleshooting dnf5 system-upgrade Command Issues

Even with careful preparation, you may encounter issues during or after the system upgrade. Below are common problems and actionable solutions to address them.

Missing Dependencies or Package Conflicts

Package conflicts can occur if certain packages are incompatible with the target Fedora release. To resolve this, use the --allowerasing option when downloading the upgrade packages. This option allows conflicting packages to be replaced or removed automatically:

sudo dnf system-upgrade download --releasever=<target_version> --allowerasing

If the issue persists, review the error output to identify the conflicting packages. You can also check the download logs for more details:

sudo dnf system-upgrade log

Uninstall problematic packages manually before retrying the upgrade if necessary.

Insufficient Disk Space

Running out of disk space is a frequent issue during upgrades. You can free up space by removing unused packages and clearing the package cache:

• To remove unused packages:

sudo dnf autoremove

• To clear cached package files:

sudo dnf clean packages

Additionally, check your current disk usage to identify large files or directories:

df -h

System Fails to Boot

If your system fails to boot after the upgrade, you can recover by booting into a previous kernel from the GRUB menu. Follow these steps:

1. Restart your system and access the GRUB menu by holding the Shift key or tapping the Esc key during boot.
2. Select an earlier kernel version from the list.

Once booted, check the system logs to identify the cause of the issue:

journalctl -xb

You can also review the upgrade logs specifically:

sudo dnf system-upgrade log --number=-1

To minimize the risk of boot failures, ensure your kernel and critical system files are updated before starting the upgrade process:

sudo dnf --refresh upgrade

Conclusion

The dnf system-upgrade command in DNF5 provides a reliable method to upgrade your Fedora system to the latest release, handling everything from package downloads to offline installation with minimal user intervention. By following the preparation steps, understanding the available options like --allowerasing and --no-downgrade, and knowing how to troubleshoot common issues, you can confidently maintain your Fedora system with the latest features, performance improvements, and security patches.