A major new release of Debian Linux operating system is a big deal for a vast number of organizations and individuals who run Linux servers and PCs. Debian is the base software for many other Linux distributions, making its reach far wider than it seems. Debian is well documented and tested software, but still, when thousands of things change in a software package, upgrading to a major new release has its challenges. Here are our tips for upgrading from Debian 10 to Debian 11 Bullseye.

Debian community members have drafted extensive upgrade instructions that cover all possible scenarios. I have taken a few shortcuts to make this guide easier to follow, but have tested that the steps worked fine both on our servers and laptops.

Here is an article that describes the new key features and improvements in Debian 11 Bullseye.

Before the upgrade

The upgrade to Debian 11 means a server or PC will be down for awhile, and will require rebooting the system, so scheduling it is important for production systems. For instance, for whatever reason, the quiet day on our public web sites tends to be Saturday, so it was the upgrade day for us. In addition, if you have a CMS like Wordpress with databases, PHP, Python or other dependencies, reserve some time for testing that everything works (see troubleshooting section for more) after the upgrade.

Tip: if you use PHP, you want to save the list of installed PHP modules before the upgrade, run (and save the list):
php -m

On a laptop, the upgrade program may require around 1GB of disk space, and on a server 500MB, but of course, it depends on your system.
Assuming the /home directory and other obvious data, like databases are already backed up, /etc usually has edited files that should be backed up.
First check the status of all packages, verifying they can be upgraded. Run:

dpkg --audit

Remove old packages from the cache:

apt clean

Remove dependency packages that have been left in the system after primary packages have been deleted:

apt autoremove

If this is a production server, it is high time to put up a Maintenance Mode sign for all services.

Upgrade

Edit the Debian software package source definitions in /etc/apt/sources.list. Replace all references to buster with bullseye. The modified lines should look something like this:

deb http://deb.debian.org/debian bullseye main contrib
deb-src http://deb.debian.org/debian/ bullseye main
deb http://security.debian.org/debian-security bullseye-security main
deb http://deb.debian.org/debian/ bullseye-updates main contrib
deb-src http://deb.debian.org/debian/ bullseye-updates main contrib

Pull the new package list to the system:

apt update

A safe way to perform the upgrade is to do it on two phases. First, a minimal upgrade. Second, the full upgrade. This makes it easier to follow the process, and take note of possible problems.

First, run (it can take a long time to finish …):

apt-get upgrade

Once the first phase has ended, run the second part (this can take even longer …):

apt full-upgrade

Take note of possible error messages, and:
reboot

When the system has started and is ready, run:
hostnamectl

The output should include lines similar to these:

Operating System: Debian GNU/Linux 11 (bullseye)
Kernel: Linux 5.10.0-8-amd64

That's it. If the upgrade didn't throw multiple serious error messages at you, it is time to test the applications and utilities work as you expect.

Troubleshooting

Upgrading a major release of any operating system is a risky proposal. Ask any enterprise IT manager whose job is to run the network and server infrastructure for the organization. These managers tend to be very reluctant to do major upgrades, but eventually, they do it once it is proven that an upgraded test system has survived long enough without problems. That's what I did - I let a test system with upgraded Debian 11 run for awhile, used it, and wrote down problems.

If you run a content management system (CMS), like Wordpress, Drupal or similar on the upgraded host, test if it works. If it doesn't, the usual suspects are dependencies on PHP and Mysql. Debian 11 upgrade may have removed an old version of PHP, but hasn't upgraded all PHP modules to the same version that comes with the Bullseye package. If you have saved the list of PHP modules before the upgrade, re-install them, but to the same version that came with the upgrade. For instance, if the new PHP version is 7.4, you probably need to:

apt-get install php7.4
… and php7.4-mbstring, php7.4-curl, and possibly others.

In addition, some features of PHP must be enabled, like:

a2enmod php7.4
a2enmod rewrite

Restart the web server, and retry if the CMS works.

Services that require python should be tested as well. For instance, we frequently use a program that requires python version 2. The upgrade removes version 2, and upgrades it to version 3. So, if you need the old version, you may have to re-install it.

On a laptop, we discovered problems with re-connecting to Wi-Fi and with touchpad configuration, but these issues may originate from KDE Plasma. Wi-Fi was disconnected in the Plasma toolbar Networks windows, and wouldn't reconnect. The Wi-Fi driver had to be reinstalled. Touchpad had to be reminded what the correct settings were.