SDB:System upgrade

(Redirected from Upgrade)
Jump to: navigation, search
This guide shows how to use Zypper to do a live distribution upgrade of openSUSE.

When updating to 15.5: see SDB:System_upgrade_to_Leap_15.5.


This page explains how to run a series of command line steps to live upgrade your system to the latest version of openSUSE. A live upgrade from the prior version is officially supported. This allows to perform a complete operating system upgrade in place, without reloading everything from scratch.

Doing a live upgrade has advantages as well as disadvantages over an offline-upgrade using an installation media.

Among the advantages are:

  • You only download the packages that need to be upgraded, thus using a lot less bandwidth.
  • During the upgrade, you can still use your workstation (even if this is not recommended); the only downtime will be the reboot after the upgrade.
  • You do not have to use a DVD, nor do you need a DVD writer. You do not have to use a USB key. This because you boot your existing system, and install everything from the net.

The disadvantages:

  • If, for any reason, the upgrade is interrupted (e.g. power outages, network disconnect) and the process cannot continue, you could be left with a broken system (that depends on where the process stopped of course).
  • If you have multiple systems to upgrade, you use bandwidth each time, so it might be better to download an ISO image.
  • It does not do all of the cleanup and maintenance that an offline DVD Upgrade does.

If you are interested in an offline upgrade, a.k.a. traditional or DVD upgrade, read offline upgrade.

Upgrading transactional-based system such as Leap Micro

Example of upgrade from e.g. Leap Micro 5.2 to Leap Micro 5.4 would be

 $ sudo transactional-update shell
 $ zypper --releasever 5.4 dup
 $ exit # exit the transactional shell
 $ reboot

User have a brand new snapshot containing the upgrade version, while he has option to boot the previous btrfs snapshot in case upgrade didn't end up well.

Migration to a new Leap release

General rules

  • Make sure that you read the list of annoying bugs for the new version you are going to install. Some of them could affect the update process. Usually, some solution or workaround is listed alongside the bug, so make sure that you are prepared for upcoming problems. Also, read the Release Notes which list changes and glitches in the new release.
  • All important data must be backed up prior to beginning the upgrade process.
  • You must update your system with the latest updates for the release you are currently running before upgrading the distribution.
  • Do not skip a release when upgrading! Example: do not upgrade from 15.1 to 15.4. Instead, from 15.1 upgrade to 15.2, then to 15.3, and only then from 15.3 upgrade to 15.4.

Note about ports (non intel architectures)

Users of Leap on ppc64le and aarch64 who migrated from to 15.3+ from older releases (before Closing the Leap Gap) are advised to remove all repositories having '/ports/' as part of URL a from their system. Existing ports repositories for Leap are just symlinks. This will ensure that they do not fetch the same data twice and will result in faster repo refresh.
Users on x86_64, s390x, and everyone who did a clean install of Leap after 15.3 (applies to all arches) are not affected.
All of the Leap rpms should be downloaded from the main oss repository,$releasever/repo/oss/

also, from non-oss repository,$releasever/repo/-non-oss/

and from update repositories, as specified in release-notes.
This does not apply to Tumbleweed users, where Tumbleweed is still actively utilizing ports subproject for non-intel architectures.

Users can install openSUSE-repos that always provides up to date repository definitions. Package was introduced in Leap 15.5, Tumbleweed and Leap Micro 5.4. Users with older releases will need to download it from manually.


We recommend to use btrfs based installation and snapper openSUSE:Snapper_Tutorial for effortless rollback.

Checking the current version

Find out what version of openSUSE you currently run as follows:

lsb_release -d


more /etc/os-release

Extra repositories handling

The supported starting point is the last openSUSE Leap release with all current updates applied, but this does not include arbitrary openSUSE Build Service repositories you may have added. We recommend that you disable all OBS repositories first, perform the upgrade, then reenable them.

Whilst zypper dup can now better handle extra repositories during an upgrade, it may be desirable to manually check if replacement repositories for the new release are available, and to either adjust the URLs in /etc/zypp/repos.d before the upgrade, or to re-add the repositories after the upgrade (see step 6).

However, a system upgrade can be the perfect occasion to remove some repositories, as too many repositories complicates maintenance. For example, suppose we have some Xfce or Plasma repository we activated to get newer versions (say we needed a feature or correct a problem that was handled in a newer version): now would be the perfect occasion to revert to the mainline version. It would be the chance to consider removing all HOME repositories that we really do not need.

Keep in mind however, that removing a repository causes the problem that every package that was installed from it will revert to another repository (if found), or deleted, or left at the old version, depending on the administrator choices. It may be a better method to leave the repository active if you do not intend to cleanup its packages immediately. A typical example would be Packman.

Each repo we remove will cause zypper to ask what to do with packages installed from them during an update: keep or upgrade with vendor change. The policy would be "keep" if we intend to add back the repository after system upgrade, or "update" otherwise. We could use "--allow-vendor-change" but this may have unintended consequences as zypper will then evaluate if any package would be better to obtain a version from another repo, considering the priorities they have.

Thus, you have to choose what road to take, as the administrator ;-)

Performing the upgrade

0. New 4096 bit RSA signing key

The new 4096 bit RSA signing key was also introduced as part of openSUSE Leap 15.5 as well as 15.4 via a maintenance update, additionally a new 4096 bit RSA backports key was introduced.

Leap 15.4 users are expected to update their system prior to upgrade of 15.5.

Users of 15.4 release currently need to import key manually with:

 rpm --import /usr/lib/rpm/gnupg/keys/gpg-pubkey-29b700a4-62b07e22.asc

and also the new 4096 openSUSE Backports key needs to be imported:

 rpm --import /usr/lib/rpm/gnupg/keys/gpg-pubkey-25db7ae0-645bae34.asc

Soon we will add automatic imports to Leap 15.4 additionally to allow seamless migration to Leap 15.5.

You can grab the keys from here 2023 gpg-pubkey-25db7ae0-645bae34.asc and 2023 gpg-pubkey-29b700a4-62b07e22.asc

1. Update system to the latest packages

zypper refresh
zypper update

For more information, read Zypper Usage.

2. Update the repos

Check if your Leap repos defined in /etc/zypp/repos.d/ are using the $releasever variable already. If they are still hard-coded with a particular Leap version number, then you need to modify them first. For example, assuming your current version is Leap 15.5, then this can be done with

sed -i 's/15.5/${releasever}/g' /etc/zypp/repos.d/*.repo
Warning: Due to Closing the Leap Gap some repos which had "openSUSE_Leap_${releasever}" for 15.3 may change target to just "${releasever}" for 15.4 ( from now on it will be the same for SLES and Leap so OBS don't need to keep two versions of binary identical rpm's). Obviously query above won't handle this so you will get "Repository 'xxxxx' is invalid." error.
Solution - follow repo URL but one level up from "openSUSE_Leap_15.3" and check available targets. If "15.4" is there just manually correct URL.

3. Refresh with the new repos

Switch and refresh all repositories to 15.6

zypper --releasever=15.6 refresh

4. Execute the full distribution upgrade

Now execute the full distribution upgrade.

Warning: It is strongly recommended that you run the upgrade outside the X-window graphical mode. Thus it is recommended you run the command from either runlevel 3 (text + network), or a virtual console. Unfortunately many times the WIFI connection is managed/available only in runlevel 5, so a virtual text console may be best while staying logged into the graphical console behind the scenes. People had their X session stopped/crashed during the upgrade, causing the upgrade to abort, which in turn left the system in an inconsistent state. To change to runlevel 3, see SDB:Switch_runlevel. To remain in runlevel 5, but use a "virtual console", type control-alt-F1 (as an example).
zypper --releasever=15.6 dup

With the above command, zypper will download all packages in advance - which is more reliable if your internet connection may fail. To download packages in heaps and install them in heaps, use:

zypper --releasever=15.6 dup --download-in-heaps

Once the dup is finished, openSUSE sets the releasever variable to the new version.

If you did the above dist upgrade before the official release date, you may have installed a Release Candidate (RC) or a milestone version and will need to repeat the final zypper dup step now to receive the final release.

5. Reboot

After upgrading, reboot the system.

6. (Optional) Add extra repositories

Search for updated openSUSE Leap 15.5 compatible third-party repositories that you used before — if you still need them — and add them.

Warning: Use with caution. Using third-party repositories may break your system or cause instabilities.
zypper addrepo --name <name> <url> <alias>

Or, if you have URL of a .repo file:

zypper ar <url.repo>

Executing zypper up may be enough to update your software from these extra repositories.


Discover and enjoy :)

In addition, zypper up can be run from time to time to ensure you have the latest available packages from the various repositories that you have enabled. YOU (Yast Online Update) only addresses security updates from the official repositories.

Legacy migrations

Upgrading from Leap < 15.2

Check if the update repository exists and is enabled

zypper repos --uri

Check if exists in one of the URI column values, and Yes in column Enabled, like the example below - substitute 15.3 with the respective version you are currently running:

#  | Alias           | Name            | Enabled | Refresh | URI
1  | repo-update     | repo-update     | Yes     | Yes     |

If the Enabled column says No, enable it by issuing the command

zypper modifyrepo --enable repo-update
where ‘repo-update’ is the name of the update repository.
Adding the update-repository
Applies: If your pre-upgrade system is 15.0 or older and the update repository does not already exist:.
zypper addrepo --check --refresh --name 'openSUSE-Leap-15.0-Update' repo-update
Replace 15.0 above with your current openSUSE version.

Note: The openSUSE Leap 15.3 adds two additional update repositories one for openSUSE Backports and one for SUSE Linux Enterprise, these additional repositories are used during online installation and delivered to Leap 15.3 system via a maintenance update of openSUSE-release with Leap 15.3 GA. This is covered in depth in the Release notes.

Moving /var/cache to a separate subvolume

Applies: If the root file system is Btrfs and you're upgrading from Leap < 15.0.

/var/cache contains a lot of very volatile data, such as the Zypper cache with RPM packages in different versions for each update. As a result of storing data that is mostly redundant but highly volatile, the amount of disk space a snapshot occupies can increase very fast. For solving this problem move /var/cache to a separate subvolume:

  • Find out the device name of the root file system:
df /
  • Identify the parent subvolume of all the other subvolumes. For openSUSE 15.1 installations, this is a subvolume named with @:
btrfs subvolume list / | grep '@'
  • If the output of this command is empty, you do not have a subvolume named with @. In that case, you may be able to proceed with subvolume ID 5 which was used in older versions of openSUSE.
  • Mount the specific subvolume to a temporary mount point:
mount /dev/<root-device> -o subvol=@ /mnt
If you don't have a @ in the subvolume name, mount subvolume ID 5 instead:
mount /dev/<root-device> -o subvolid=5 /mnt
  • /mnt/var/cache can already exist and could be the same directory as /var/cache. To avoid data loss, move it:
mv /mnt/var/cache /mnt/var/cache.old
  • Create a new subvolume:
btrfs subvol create /mnt/var/cache
  • If there is now a directory /var/cache.old, move it to the new location:
mv /var/cache.old/* /mnt/var/cache
If that is not the case, instead do:
mv /var/cache/* /mnt/var/cache/
  • After moving (optionally) remove /mnt/var/cache.old:
rm -rf /mnt/var/cache.old
  • Unmount the subvolume from the temporary mount point:
umount /mnt
  • Add an entry to /etc/fstab for the new /var/cache subvolume. Use an existing subvolume as a template to copy from. Make sure to leave the UUID untouched (this is the root file system's UUID) and change the subvolume name and its mount point consistently to /var/cache.
  • Mount the new subvolume as specified in /etc/fstab:
mount /var/cache

Migrating between architectures

Update from 32-bit openSUSE to Leap is not supported. Leap is 64-bit only. If your hardware has x86_64 support, you can upgrade Leap to 64-bit first. See 32-bit to 64-bit upgrade - note these instructions have only been tested on 13.2 and may no longer be applicable.

On the AArch64 architecture (64-bit ARM), upgrading from Leap 15.0 to Leap >= 15.1 is not supported. Please do a fresh installation on those systems.

Be aware that, in principle, this upgrade process is considered “best effort” only. This means that due to some third-party packages and the myriad of possible configurations, it is possible for some combinations to cause failure upon upgrade.

Other migration scenarios

Migration to openSUSE Tumbleweed

Note: according to factory mail list it has been tested in openQA direct upgrade from openSUSE 12.x to Tumbleweed (till snapshot 1101). Currently (Nov 2017) the process is tested from 13.x and 42.x directly to TW. However, this does not mean that you should do it! You could hit an unknown problem.

Migration to SUSE Linux Enterprise

If you're interested in migration from openSUSE Leap to SUSE Linux Enterprise. Then please follow our guide for migrating to SUSE Linux Enterprise.