quick-docs/en-US/dnf-system-upgrade.adoc

= DNF system upgrade

'''

[IMPORTANT]
======

This page was automatically converted from https://fedoraproject.org/wiki/DNF_system_upgrade

It is probably

* Badly formatted
* Missing graphics and tables that do not convert well from mediawiki
* Out-of-date
* In need of other love

Pull requests accepted at https://pagure.io/fedora-docs/quick-docs

Once you've fixed this page, remove this notice, and update
`_topic_map.yml`.

Once the document is live, go to the original wiki page and replace its text
with the following macro:

....
{{#fedoradocs: https://docs.fedoraproject.org/whatever-the-of-this-new-page}}
....

======

'''


[[what-is-dnf-system-upgrade]]
What is DNF system upgrade?
~~~~~~~~~~~~~~~~~~~~~~~~~~~

https://github.com/rpm-software-management/dnf-plugin-system-upgrade[dnf-plugin-system-upgrade]
is a plugin for the link:Dnf[dnf] package manager which handles system
upgrades. It is the recommended command line upgrade method for Fedora
21 and later (Except Atomic Host, which uses rpm-ostree; for that see
Atomic_Host_upgrade).

[[what-does-dnf-system-upgrade-do]]
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]]
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 https://getfedora.org/en/workstation/[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 :
+
....
$ sudo dnf upgrade --refresh
....
+
(Don't type the `$` in these commands; that just indicates that you type
this at a terminal prompt as a non-root user.)
+
After updating, we recommend you reboot your computer, especially if
you've just installed a new kernel. +
* Please note that there is
link:Common_F23_bugs#plymouth-theme-upgrade[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.
* Double check your DNF configuration in , if you have done any custom
configuration (either manually or via third-party tool), it's
recommended to revert it to default before updating and upgrading your
system.
3.  Install package:
+
....
$ sudo dnf install dnf-plugin-system-upgrade
....
4.  Download the updated packages: \{\{#tag:pre|$ sudo dnf
system-upgrade download --refresh --releasever=}} 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 **, but if you're running Fedora , you might want to upgrade
just to Fedora . You can also use for upgrading to Branched or `rawhide`
for upgrading to Rawhide (warning: those are not stable releases).
* If you are upgrading to Rawhide, you will need to import the rpm gpg
key for it. This will be the highest numbered key version in . For
example if there is a Branched release that is , then you should look
for a , and if there is currently no Branched release, it will be .
\{\{#tag:pre|$ sudo rpm --import
/etc/pki/rpm-gpg/RPM-GPG-KEY-fedora--primary}}
5.  If some of your packages have unsatisfied dependencies, the upgrade
will refuse to continue until you run it again with an extra option.
This often happens with packages installed from third-party repositories
for which an updated repositories hasn't been yet published. Please
study the output very carefully 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 sometimes see more
details if you add option to the command line.
* If you want to remove/install some packages manually before running
`dnf system-upgrade download` again, it's advisable to perform those
operations with `--setopt=keepcache=1` dnf command line option.
Otherwise the whole package cache will be removed after your operation,
and you'll need to download all the packages once again.
6.  Trigger the upgrade process:
+
....
 $ sudo dnf system-upgrade reboot
....
+
This will reboot your machine immediately. The system should boot again
into Fedora using the same kernel, but this time, the upgrade process
appears on the boot screen.
7.  Wait for the upgrade process to complete.

[[frequently-asked-questions]]
Frequently Asked Questions
~~~~~~~~~~~~~~~~~~~~~~~~~~

[[how-do-i-report-issues-that-i-find-with-upgrades]]
How do I report issues that I find with upgrades?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

First see link:Common_F{{FedoraVersionNumber}}_bugs[Common
F\{\{FedoraVersionNumber}} bugs] or
link:Common_F{{FedoraVersionNumber[next}} bugs] to check if the problem
is a very prominent issue we already know of. If it is not there,
https://bugzilla.redhat.com/buglist.cgi?product=Fedora&component=dnf-plugin-system-upgrade&resolution=---[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. Please
follow the bug reporting instructions mentioned in
https://github.com/rpm-software-management/dnf-plugin-system-upgrade[this
README] and in `man dnf.plugin.system-upgrade`.

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]]
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
parameter if you need to do so for any reason (not recommended, you're
then opened to attacks from malicious software).

[[will-packages-in-third-party-repositories-be-upgraded]]
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-upgrade-from-an-end-of-life-release]]
Can I upgrade from an link:End_of_life[End of life] release?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Note that Fedora strongly recommends against ever running an end-of-life
release on any production system, or any system connected to the public
internet, in any circumstances. You should never allow a production
Fedora deployment to reach end-of-life in the first place.

With that in mind, if you do have an end-of-life release newer than
Fedora 20 installed on a system you cannot just discard or re-deploy,
you can attempt to upgrade it, though this is a less-tested and
less-supported operation. You can 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. It is
not possible to state with certainty which approach is more likely to be
successful.

If you attempt to upgrade across more than two releases in one
operation, please also read the link:#multi[next answer].

If you have Fedora 20 or earlier installed, you cannot upgrade with DNF
system upgrade alone. You must upgrade at least part of the way
link:Upgrading_Fedora_using_package_manager[using bare or ]. You can
either upgrade to Fedora 21 that way and then upgrade the rest of the
way using DNF system upgrade, or you can attempt the entire upgrade
using bare or . Note this method is in itself not an officially
recommended upgrade mechanism. To be frank, any upgrade from Fedora 20
or earlier is very much done 'at your own risk'.

[[how-many-releases-can-i-upgrade-across-at-once]]
How many releases can I upgrade across at once?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The most common scenario is an upgrade across just one release (e.g. to
). However, for the first month or so after a new release comes out,
upgrades from the last-but-one release to that release are 'supported',
in the sense that we include this scenario in the
link:Fedora_Release_Criteria[Fedora Release Criteria], test it for at
least clean installs of supported package sets, and will treat bugs
discovered in such upgrades as significant. The
link:Fedora_Release_Life_Cycle[Fedora Release Life Cycle] is
specifically designed to provide this approximate one month 'grace
period' so you can choose to upgrade long-lived systems only once every
two releases, rather than having to do it every release.

Around a month after the new release comes out, the last-but-one release
goes link:End_of_life[End of life], at which point the
link:#eol[previous question] applies. Still, that upgrade is still
pretty likely to work successfully for some time after the release goes
end-of-life.

Upgrades across more than two releases are not 'supported', and issues
encountered in such upgrades may not be considered significant bugs.
Note that any upgrade across more than two releases must by definition
be an upgrade from an end-of-life release, and so the link:#eol[previous
question] applies here too.

When upgrading across multiple releases, you may find you need to
link:Upgrading_Fedora_using_package_manager#packagekey[import the target
release package signing key manually]. Fedora releases usually only have
the package signing keys for the next two releases installed (because
they go end-of-life before the N+3 release is branched). Before Fedora
22, it was not consistently the case that every release had keys for the
next two releases, either. If dnf complains about a missing key, this is
what you must do.

[[can-i-use-dnf-system-upgrade-to-upgrade-to-a-pre-release-e.g.-a-beta]]
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.

[[optional-post-upgrade-tasks]]
Optional post-upgrade tasks
~~~~~~~~~~~~~~~~~~~~~~~~~~~

These are tasks you can do after a successful upgrade. *They are mostly
intended for power users. If you are a general user who doesn't use
terminal daily, you don't need to worry about this.*

[[update-system-configuration-files]]
Update system configuration files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Most configuration files are stored in `/etc`. If there are any updates
to them and you touched some of those files before, RPM creates new
files with either `.rpmnew` suffix (the new default config file), or
`.rpmsave` suffix (your old config file backed up). You can search for
these files, go through the changes and make sure your custom changes
are still included and the new defaults are applied as well. A tool that
tried to simplify this is . Install the package, and then use it as:

`$ sudo rpmconf -a`

See more information in its manual page.

[[clean-up-old-packages]]
Clean up old packages
^^^^^^^^^^^^^^^^^^^^^

You can see list of packages with broken dependencies like this:

`$ sudo dnf repoquery --unsatisfied`

Ideally there should be none. If there are some, consider removing them,
because they are not likely to work properly anyway.

You can see duplicated packages (packages with multiple versions
installed) like this:

`$ sudo dnf repoquery --duplicated`

For ordinary packages, just the latest version should be installed. But
there can be exceptions to the rule, only remove what you are sure you
no longer need.

Some packages might stay on your system while they have been removed
from the repositories. See them using:

`$ sudo dnf list extras`

If you don't use these, you can consider removing them:
`dnf remove $(dnf repoquery --extras --exclude=kernel,kernel-\*)`.
Please note that this list is only valid if you have a fully updated
system. Otherwise you'll see all installed packages which are no longer
in the repositories, because there is a newer update available. So
before acting on these, make sure you have run `sudo dnf update` and
generate the list of extra packages again. Also, this list might contain
packages installed from third-party repositories for which an updated
repository hasn't been published yet. This often involves e.g. RPM
Fusion or Dropbox.

You can remove no-longer-needed packages using:

`$ sudo dnf autoremove`

but *beware* that dnf decides that a package is no longer needed if you
haven't explicitly asked to install it and nothing else requires it.
That doesn't mean that package is not useful or that you don't use it.
*Only remove what you are certain you don't need*. There's a known bug
in PackageKit which doesn't mark packages as user-installed, see
https://bugzilla.redhat.com/show_bug.cgi?id=1259865[bug 1259865]. If you
use PackageKit (or GNOME Software, Apper, etc) for installation, this
output might list even important apps and system packages, so beware.

[[resolving-post-upgrade-issues]]
Resolving post-upgrade issues
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

*Only follow up these steps if you have troubles with your upgraded
system. It should not be needed in the vast majority of upgrades.*

[[rebuilding-rpm-database]]
Rebuilding RPM database
^^^^^^^^^^^^^^^^^^^^^^^

If you see warnings when working with RPM/DNF tools, your database might
have gotten corrupted for some reason. It is possible to rebuild it and
see if resolves your issues. Always back up `/var/lib/rpm/` first. To
rebuild the database, run:

`$ sudo rpm --rebuilddb`

[[using-distro-sync-to-resolve-dependency-issues]]
Using distro-sync to resolve dependency issues
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The system upgrade tool uses distro-sync method by default. If your
system stayed partly unupgraded or you see some package dependency
issues, you might try to fix it by running another distro-sync manually.
This tries to make your installed packages exactly the same version as
in currently enabled repositories, even if it meant downgrading some
packages:

`$ sudo dnf distro-sync`

A stronger variant also allows to remove package for which package
dependencies can't be satisfied. Always carefully review which packages
are going to be removed before confirming this:

`$ sudo dnf distro-sync --allowerasing`

[[relabel-files-with-latest-selinux-policy]]
Relabel files with latest SELinux policy
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you see warnings that some actions were not allowed because of
current SELinux policy, it might be a case of having some files
incorrectly label with SELinux permissions. This might happen in case of
some bug or if you had SELinux disabled in some point of time in the
past. You can relabel the whole system by running:

`$ sudo touch /.autorelabel`

and rebooting. The next boot will take a long time and will check and
fix all SELinux labels on all your files.
'''

See a typo, something missing or out of date, or anything else which can be
improved? Edit this document at https://pagure.io/fedora-docs/quick-docs.