DNF system upgrade

What is DNF system upgrade?

dnf-plugin-system-upgrade is a plugin for the Dnf package manager which handles system upgrades. It is the recommended upgrade method for Fedora since the release of Fedora 23 Beta. The Changes/DNF_System_Upgrades page documents the initial introduction of this mechanism.

DNF System Upgrade can upgrade systems running Fedora 21 or later.

What does DNF system upgrade do?

DNF system upgrade can upgrade your system to a newer release of Fedora, using a mechanism similar to that used for offline package updates. The updated packages are downloaded while the system is running normally, then the system reboots to a special environment (implemented as a systemd target) to install them. Once installation of the updated packages is complete, the system reboots again to the new Fedora release.

How do I use it?

1. Back up your important data. Every system change is potentially risky, be prepared. In case you update your workstation, it is also wise to download a Workstation Live image and make sure your hardware (graphics card, wifi, etc) works well with the latest kernel and drivers.
2. Update your system using the standard updater for your desktop or pkcon or dnf:
   • sudo dnf update --refresh
   • It is recommended to reboot the computer, especially if you've just installed a new kernel.
   • Please note that there is an issue if you use a non-default plymouth boot theme. If you do, please follow the issue description to make sure your upgrade will not be affected.
3. Install the dnf-plugin-system-upgrade package:
   • sudo dnf install dnf-plugin-system-upgrade
4. Download the updated packages:
   • sudo dnf system-upgrade download --releasever=41
   • Change the --releasever= number if you want to upgrade to a different system release. Most people will want to upgrade to the latest stable release, which is 41, but if you want, you can also use 42 or rawhide (warning: those are not stable releases).
   • If some of your packages have unsatisfied dependencies, the upgrade will refuse to continue until you run it again with an extra --allowerasing option. This often happens with packages installed from third-party repositories for which an updated repositories hasn't been yet published. Please study very careful the output and examine which packages are going to be removed. None of them should be essential for system functionality, but some of them might be important for your productivity.
   • In case of unsatisfied dependencies, you can see more details if you add --best option to the command line.
5. Trigger the upgrade process:
   • sudo dnf system-upgrade reboot
6. Wait for the upgrade process to complete.

Frequently Asked Questions

How do I report issues that I find with upgrades?

First see Common F41 bugs or Common F42 bugs to check if the problem is a very prominent issue we already know of. If it is not there, search for an existing bug report. If you do not see a report that matches your symptoms, you can file a new report from the search page.

If you hit issues after upgrade with a specific package, file a bug against the package with which you are having issues.

Does DNF system upgrade verify the software it runs or installs during upgrade?

Yes. The package signing keys for newer Fedora releases are sent to older Fedora releases in order to allow DNF to verify the integrity of the packages it downloads. You can disable this function with the --nogpgcheck parameter if you need to do so for any reason.

Will packages in third party repositories be upgraded?

Yes, if they are set up like regular DNF repositories and do not hard code the repository path. Commonly-used third party repositories usually work fine, but if you attempt to upgrade prior to or soon after an official Fedora release, they may not have updated their repository paths yet, and DNF may be unable to find their packages. This will usually not prevent the upgrade running successfully, though, and you can update the packages from the third-party repository later.

Can I use DNF system upgrade to upgrade to a pre-release (e.g. a Beta)?

Yes. It should always be possible to attempt such an upgrade. Of course, this function is as subject to temporary breakage as is any other aspect of a pre-release, and generally speaking, the earlier the release in question, the less likely it is to work without problems.

Cleaning Up Post Upgrade

Rebuild RPM DB

It is worth rebuilding the RPM DB to prevent RPMDB checksum error when doing a distribution sync:

sudo rpm --rebuilddb

distro-sync

There are a collection of post-upgrade things to do. Some of which are fixed by doing a distro sync:

(If you run dnf the first time and you're behind a proxy add your proxy settings to /etc/dnf/dnf.conf)

sudo dnf distro-sync --setopt=deltarpm=0

Update system configuration files

The rpmconf tool searches for .rpmnew, .rpmsave and .rpmorig files and asks you what to do with them: Keep current version, place back old version, watch the diff or merge.

sudo dnf install rpmconf

sudo rpmconf -a

SELinux

Relabeling system files is necessary after system upgrades and changes in selinux policy.

To relabel your file system a reboot advised

sudo touch /.autorelabel && reboot

Package Cleanup

Cleanup - yum-utils / package-cleanup is in process of migration to dnf, but not all the previous features may be available.

Problems (package-cleanup problems) sudo dnf repoquery --unsatisfied

Duplicates (package-cleanup --dupes) sudo dnf repoquery --duplicated

Orphans (package-cleanup --orpahans) sudo dnf list extras

A few comments on old/orphaned packages. If you are using third party repos, such as rpmfusion, newer packages may not be available at the time of the upgrade. You may continue to use old packages (or use the old repositories for packages) until new ones become available.

You can list old packages with

{command|dnf list installed | grep fc22}}

Review the package list before you remove old packages as removing packages may cause problems then leaving them installed.

To remove orphaned packages

sudo dnf autoremove

Again, be sure to review the list before removing these packages as removing packages may cause more problems then leaving them alone.