DNF System Upgrade
This page has been converted from the Fedora Project Wiki and cleaned up for publishing here on the Fedora Docs Portal, but it has not yet been reviewed for technical accuracy. This means any information on this page may be outdated or inaccurate. Reviews for technical accuracy are greatly appreciated. If you want to help, see the README file in the source repository for instructions.
dnf-plugin-system-upgrade is a plugin for the DNF package manager and is used to upgrade your system to the current release of Fedora.
For Atomic Host, which uses rpm-ostree, you may refer to Read The Docs: rpm-ostree for details.
This is the recommended command-line upgrade method for Fedora 21 and later and works as follows:
Packages are downloaded while the system is running normally
The system reboots into a special environment (implemented as a systemd target) to install them
Upon completion, the system reboots into the new Fedora release
Back up your data before performing a system-wide upgrade as every system upgrade is potentially risky. As a precaution, download the Fedora Workstation Live image in the event something goes wrong.
To update your Fedora release from the command-line do:
sudo dnf upgrade --refresh
and reboot your computer.
Install the dnf-plugin-system-upgrade package if it is not currently installed:
sudo dnf install dnf-plugin-system-upgrade
Download the updated packages (replace N with the release version):
sudo dnf system-upgrade download --refresh --releasever=N
Trigger the upgrade process. This will restart your machine into the upgrade process:
sudo dnf system-upgrade reboot
Once the upgrade process to complete, your system will reboot into the updated release version of Fedora.
These are some of the tasks you can do after a successful upgrade.
This section is mainly intended for power users. If you are a general user who doesn’t use the terminal daily, you may skip this section.
Most configuration files are stored in the
If you have changed the package’s configuration files, RPM creates new files with either
.rpmnew (the new default config file), or
.rpmsave (your old config file backed up).
You can search for these files, or use the
rpmconf tool that simplifies this process. To install rpmconf, enter:
dnf install rpmconf
Once the install is complete enter:
sudo rpmconf -a
For more information you can refer to the man pages (
You can see a list of packages with broken dependencies by typing:
sudo dnf repoquery --unsatisfied
The list should be empty, but if this is not the case consider removing them as they are not likely to work.
You can see duplicate packages (packages with multiple versions installed) with:
sudo dnf repoquery --duplicated
For packages from the official repositories, the latest version should be installed. However, some packages that are still on your system may no longer be in the repositories. To see a list of these packages do:
sudo dnf list extras
If you see a package you do not need, or use, you can remove it with:
sudo dnf remove $(dnf repoquery --extras --exclude=kernel,kernel-\*)
You can safely remove packages no longer in use with:
sudo dnf autoremove
DNF decides that a package is no longer needed if you haven’t explicitly asked to install it and nothing else requires it. However, that doesn’t mean that the package is not useful or that you don’t use it. Only remove what you are sure you don’t need.
Only follow these steps if you encounter problems with your upgraded system.
If you see warnings when working with RPM/DNF tools, your database might be corrupt.
It is possible to rebuild it to see if resolves your issues. Always back up
To rebuild the database, run:
sudo rpm --rebuilddb
The system upgrade tool uses
dnf distro-sync by default.
If your system is partly upgraded or you see some package dependency issues, try running another distro-sync manually to see if this fixes the problem.
This will attempt to make your installed packages the same version in your currently enabled repositories, even if it must downgrade some packages:
sudo dnf distro-sync
You can also use the
--allowerasing option will remove packages with dependencies that can not be satisfied.
Always review which packages will be removed before confirming this:
sudo dnf distro-sync --allowerasing
If you encounter any warnings regarding policies with SELinux, some files may have incorrect SELinux permissions. This may happen if SELinux was disabled at some point in the past. To relabel the entire system run:
sudo touch /.autorelabel
The boot process may take a long time as it is checking and fixing all SELinux permission labels on all the files in your system.
If you do not see a report that matches your symptoms, you can file a new report from the search page.
Please follow the bug reporting instructions mentioned in the README from the github repo or in
If you encounter any issues after the upgrade with a specific package, file a bug against the package with which you are having issues.
Yes. The package signing keys for the newer Fedora release are sent to older Fedora releases to allow DNF to verify the integrity of the downloaded packages. You can disable this function if needed, but is not recommended as you will be open to attacks from malicious software.
Yes, if they are configured like regular DNF repositories and the version numbers are not hard-coded in the repository file (usually found in
Commonly used third-party repositories like RPM Fusion should work.
However, if attempting to upgrade prior to, or soon after, an official Fedora release, they may not have updated their repository paths, and DNF may be unable to find their packages.
Usually, this should not prevent the upgrade from running successfully.
Also, you can update packages from the third-party repository later.
It is strongly recommended to upgrade an EOL release on any production system, or any system connected to the public internet.
Any upgrade from Fedora 20 or earlier is done at your own risk as DNF was not the default package management tool. However, if you do have a release newer than Fedora 20 that is EOL, you can attempt to do an upgrade, but this method is not supported. You may try to upgrade through intermediate releases until you reach a currently-supported release, or try to upgrade to a currently-supported release in a single operation. Again this is un-supported and is at your own risk.
It is highly recommended to upgrade across just one release (e.g. 27 to 28). However, for the first month or so after a new release, upgrades from the last-but-one release are 'supported' (N-2, where N is the current release). The Fedora Release Life Cycle is specifically designed to provide this approximate one month "grace period" to allow users the choice to upgrade their systems on a yearly basis, or once every two releases.
Around a month after the new release comes out, the last-but-one release becomes End Of Life (EOL). The upgrade is likely to work successfully after the release goes end-of-life, but the time period after the new release may be uncertain.
Upgrades across more than two releases are not supported, and issues encountered with such upgrades may not be considered significant bugs.
When upgrading across multiple releases, you may need to import the GPG key for the release you want to update to. You can do this with:
gpg --quiet --with-fingerprint /etc/pki/rpm-gpg/RPM-GPG-KEY-fedora-N-primary
(where N is the Fedora version.)
Refer to the getfedora.org FAQ on Keys for details.