How To Upgrade To Debian 13

In the video below, we show you how to upgrade Debian family computers to Debian 13

Earlier this year Debian released a major upgrade of their Operating System, Debian 13, aka Trixie

As well as updated applications with newer features, this brings a newer kernel which should support newer firmware and offer better performance

Now at the time of recording, the latest version is 13.1 which should have had plenty of testing from regular users

So now is as good a time as ever to upgrade any Debian family of computers that are based on Debian 12

But how do you upgrade a computer from say Bookworm to Trixie?

Useful links:
https://www.debian.org/releases/stable/release-notes/upgrading.html
https://www.debian.org/releases/stable/release-notes/issues.en.html
https://www.debian.org/releases/stable/release-notes/upgrading.html#possible-issues-during-upgrade

Assumptions:
Now I have to assume that your computer is running Debian 12

That’s because you can’t upgrade from say Debian 11, aka Bullseye, to Debian 13

You would have to upgrade that to Debian 12 first

Because of the complexity, I’m also assuming you have a standard installation of Debian

The release notes for instance mention that if you are doing APT pinning, you need to disable that

But that’s just one example of the things you have to look out for

And as I can’t know what non-standard changes you might have made, if any, I’ll only cover standard Debian installations in this video

First Things First:
Most computers will probably be fine to upgrade but do check for potential issues before doing anything

Known issues can be found here
https://www.debian.org/releases/stable/release-notes/issues.en.html

Check all of them because if any of these apply to your computer or setup, you could run into critical issues

For example, i386 CPUs are no longer supported, MariaDB needs to be shutdown, etc.

Also, be aware of possible issues you may run into when upgrading https://www.debian.org/releases/stable/release-notes/upgrading.html#possible-issues-during-upgrade

Now before upgrading a computer you should always make sure you have a backup of any data and ideally important system files

There are various ways to do this, but that’s outside the scope of this video

If possible, test your upgrade process on a less critical computer first, ideally a virtual machine

Not every upgrade is the same, but this at least allows you to test the process and if something goes wrong it will be less impacting

And last but not least, make sure any applications you are using will still work with Debian 13

I have MySQL installed on a computer for instance and at the time of recording it still isn’t ready for use with Debian 13

Fortunately I can put that in a container to get around this or migrate to MariaDB instead

Upgrade Debian 12:
Before you make a major upgrade you should make sure your computer is running the latest point release of Bookworm

While you can upgrade a Linux computer remotely via an SSH session, it’s better to do this through a console session

The risk of being locked out is simply too high because if something goes wrong, the computer could then be out of service and you may lose remote access to it

So if the computer is in a remote location, while you can still perform the upgrade through an SSH session, first make sure you have remote console access or have onsite assistance

The first thing to do is to close as many applications as possible

After all, we’ll be upgrading applications as well as the OS

First, make sure you have a metapackage installed

dpkg -l 'linux-image*' | grep ^ii | grep -i meta

If there is no output then use the link to see what needs to be done https://www.debian.org/releases/stable/release-notes/upgrading.html#upgrading-your-kernel-and-related-packages

Now we’ll update the package repository first

sudo apt update

Then we’ll make sure existing packages are up to date

sudo apt full-upgrade

This is a bit more aggressive than using apt upgrade

For example, if package A needs to be upgraded, but it requires package B to be removed, then apt full-upgrade will go ahead and do that, whereas apt upgrade would refuse to upgrade package A

But the goal here is to ensure all packages are up to date, so this is one of those occasions we use apt full-upgrade

Warning: Do check which packages, if any, will be removed before committing when prompted

Remove Obsolete Packages:
Debian recommends removing obsolete packages before carrying out a major upgrade

First check what, if anything, is considered to be obsolete

sudo apt list '?obsolete'

If anything is reported, carefully consider how to deal with these packages

Maybe you have software which is now deprecated, in which case an upgrade to Trixie should probably be held off

In once case for me, it flagged up draw.io which was manually installed as a Debian package

Now if you do need to remove obsolete packages Debian recommends purging them

Warning: This also removes configuration files so you might want to back these up if possible if you plan to re-install any software after the upgrade, but bear in mind that configurations can change over versions

To purge all obsolete packages in one go, Debian suggest running this command

sudo apt purge '?obsolete'

You may find you have to repeat this process multiple times i.e. once packages are purged, check there’s nothing left to remove

sudo apt list '?obsolete'

Configuration files from removed packages may be left behind and this can be checked by running this command

sudo apt list '?config-files'

Carefully check through the list, although it’s unlikely anything listed is still needed

Assuming any were found, you can remove them all with one command

sudo apt purge '?config-files'

As before though, it would best to repeatedly check there is nothing left

sudo apt list '?config-files'

Remove Non-Debian Packages:
Debian recommends removing non-Debian packages before carrying out a major upgrade

This makes sense as leaving these installed could cause later issues and there’s even the potential the upgrade itself could fail

To check for packages not in the official repository we can run this command

sudo apt list '?narrow(?installed, ?not(?origin(Debian)))'

As Debian warn though, there’s no guarantee that this will list everything so it helps to know what software you installed

For me it flagged up the Brave web browser for instance, which was installed manually

NOTE: Do backup the configuration of any application you need to remove and plan to re-install. In the case of this web browser for instance, I would export the bookmarks in this case

As an example of removing the brave browser I used these commands

sudo apt purge brave-browser
sudo apt purge brave-keyring

As with the obsolete packages, I’m opting to use purge rather remove because it should completely remove the application and any configuration files

Once each package has been removed, check again

sudo apt list '?narrow(?installed, ?not(?origin(Debian)))'

It’s also worth checking for key-rings that are no longer needed as sometimes they aren’t removed

ls -l /usr/share/keyrings/

Also check for 3rd party repository files as we don’t want to see any; Any 3rd party software should be re-installed after the upgrade

ls -l /etc/apt/sources.list.d

As an example, I found a file left over from the brave browser that had been installed on the computer, so that was removed

sudo rm /etc/apt/sources.list.d/brave-browser-release.list

Remove Leftover Configuration Files:
Package upgrades and removals can leave behind other configuration files and Debian recommends these are removed

One way to find these is to run this command

sudo find /etc -name '*.dpkg-*' -o -name '*.ucf-*' -o -name '*.merge-error'

If any files do show up in the output, check what these are and assuming there’s no foreseen issue then remove them

As an example, when I ran this command on a computer it returned this result

/etc/ca-certificates.conf.dpkg-old

At some point it seems a backup was made of this file

ca-certificates.conf

So I’ll remove it

sudo rm /etc/ca-certificates.conf.dpkg-old

Non-Free Firmware:
Debian suggests that if you have non-free firmware installed in your computer you should update the APT sources list

This change in strategy came about around Debian 12 aka Bookworm and I’d already updated my source list with this as a result

This is what the typical /etc/apt/sources.list file tends to look after doing that

deb http://deb.debian.org/debian/ bookworm main non-free-firmware
deb-src http://deb.debian.org/debian/ bookworm main non-free-firmware

deb http://security.debian.org/debian-security bookworm-security main non-free-firmware
deb-src http://security.debian.org/debian-security bookworm-security main non-free-firmware

deb http://deb.debian.org/debian/ bookworm-updates main non-free-firmware
deb-src http://deb.debian.org/debian/ bookworm-updates main non-free-firmware

In any case, by having this prior to performing the upgrade, the computer should be able to source the necessary software and/or firmware that’s needed for your computer

TIP: Unless you’re compiling software, you don’t need the deb-src lines. These are for source files so in most cases they may as well be removed to leave these lines

deb http://deb.debian.org/debian/ bookworm main non-free-firmware

deb http://security.debian.org/debian-security bookworm-security main non-free-firmware

deb http://deb.debian.org/debian/ bookworm-updates main non-free-firmware

Remove Proposed-Updates:
If you’ve added proposed-updates to your APT source files, Debian recommends you remove these entries

Proposed-updates are typically going to be used by testers as this can contain packages that will be released in the next stable release

In other words, it’s an opportunity to test package updates ahead of official release

For a major upgrade, it’s best the computer is only running a stable release

Unofficial Sources:
According to the release notes, you may find unofficial sources are removed from the APT source list as part of the upgrade

This is to avoid the potential for conflicts

Now earlier I did cover checking the /etc/apt/sources.list.d/ folder

But all the same, do make sure any software you plan to add afterwards will support Debian 13 before considering an upgrade

As before, I ran into the issue of MySQL not being ready

Also, be prepared to take additional steps once the OS is upgraded

You should also look for changes in deployment and configuration for the newer OS

For example, I found one package now has different folder permissions for where the configuration file is stored

This caused me problems as I was running the software with a different UID/GID for the user and the container broke as a result of migrating from Bookworm to Trixie

APT Pinning:
As mentioned early on, if you are using APT pinning you should disable this

This is usually only done when software has a dependency on older packages to run

I think it’s more likely to be used for in-house software development

But if this is left in place, it prevents packages being upgraded to newer versions and this is essential in a major upgrade

I you haven’t already taken care of this, don’t go any further

Check Package Status:
Before upgrading you should check the status of all packages

sudo dpkg --audit

If there are any issues reported you need to address them

It’s also advised to check the status of packages

sudo dpkg -l

Unfortunately it’s a long list to work through but essentially focus on the left column

What you want to see is all lines beginning with ii as it means the desired and current states are installed

Any packages on hold should be upgraded prior to a major upgrade

You should learn if any are from the previous command but you can also double check with this command

sudo apt-mark showhold

If there’s nothing returned you’re fine

Now packages are typically put on hold because a previous upgrade caused something to break

If any packages are reported as being on hold you’ll want to fix the issue first, once that’s done you can remove the hold

sudo apt-mark unhold package_name

Then you should upgrade the package(s)

Now if this can’t be done, then you should hold off on an upgrade to Trixie until the issue is resolved

Tidy Up:
At this stage I’d be inclined to do some final tidy up work

First we’ll remove unneeded packages

sudo apt autoremove

And we’ll clean up the package cache

sudo apt clean

A reboot would also make sense, especially if the kernel has been upgraded

sudo reboot now

New APT Source Style:
The format for APT sources has changed to a deb822-style and there should be a migration to this prior to upgrading to Trixie

In the more common format, there is a main file called /etc/apt/sources.list

There is also a folder called /etc/apt/sources.list.d/ in which it was advised to place additional source files for other repositories

This way you could add new repository sources without them being overwritten in a future OS update

Going forward, Debian sources will now be referenced in /etc/apt/sources.list.d/debian.sources

It would make sense to backup the existing file rather than deleting it

sudo mv /etc/apt/sources.list /etc/apt/sources.list.bak

My existing file typically looks more or like this

deb http://deb.debian.org/debian/ bookworm main non-free-firmware

deb http://security.debian.org/debian-security bookworm-security main non-free-firmware

deb http://deb.debian.org/debian/ bookworm-updates main non-free-firmware

Now I’ll create a new file to replace this, but with the new format AND to have this reference Trixie instead of Bookworm

sudo nano /etc/apt/sources.list.d/debian.sources

Types: deb
URIs: https://deb.debian.org/debian
Suites: trixie trixie-updates
Components: main non-free-firmware
Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg

Types: deb
URIs: https://security.debian.org/debian-security
Suites: trixie-security
Components: main non-free-firmware
Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg

This covers the main files and updates, plus security updates

One thing that’s really good here is a shift to HTTPS rather than HTTP. This gives the software updating process an additional layer of security and integrity but it’s also using encryption

Granted, the apt process checked file integrity anyway, but now we get the extra protection of TLS

And although that original format did support HTTPS, once the Debian mirrors supported it, the default Debian 12 deployment still used HTTP

Going forward, it would also make sense to use this new format for 3rd party repositories you add, so do check when you download and install anything

Upgrading to Trixie:
With our APT sources now referencing packages for Trixie we’ll update the package list

sudo apt update

Next we’ll check if there is enough disk space available for the upgrade

sudo apt -o APT::Get::Trivial-Only=true full-upgrade

Now it doesn’t actually let you perform an upgrade, the command deliberately forces this to halt so we can just check the disk space calculation

If you do get a warning about a lack of disk space though I suggest checking here for further suggestions
https://www.debian.org/releases/stable/release-notes/upgrading.html#make-sure-you-have-sufficient-space-for-the-upgrade

Because this is a major upgrade, Debian recommends a two step approach

First, carry out a minimal upgrade

sudo apt upgrade --without-new-pkgs

At some point the process will halt as apt-listchanges covers what is being changed

You can keep pressing the space key to scroll through these or press q to quit and continue the upgrade

Personally I prefer to automate the package upgrade process rather than deciding for each one, so when prompted I choose Yes to restart services without being prompted

While packages are being upgraded, the installation process will warn you if a configuration file on the computer is different to the one provided with the newer package

This happens when you change a configuration file of a package

As an aside, ideally you should override a configuration file rather than making changes to it

In other words, some packages provide an override option in the form of a *.d folder

Adding files with your own settings in that folder, will override the settings in the developer’s configuration file

Although it’s not always possible to do this

In that case, because an upgrade may bring new features or features may be deprecated, I prefer to accept the new file and customise it afterwards

Once the initial upgrade is done, we’ll perform a full upgrade

sudo apt full-upgrade

As before, the process will likely be halted by apt-listchanges

You may also be prompted if services need restarting and any config files need replacing

Once the upgrade completes it’s then a matter of rebooting the computer

sudo reboot now

Don’t be surprised to see warnings, but hopefully all should be well

Tidy Up:
Once the computer is back up and running it makes sense to check things are working and then do a final tidy up

First we’ll remove unneeded packages

sudo apt autoremove

TIP: The newer APT will do highlighting, so red isn’t a warning, just packages that will be removed

And then we’ll clean up the package cache

sudo apt clean

As part of the upgrade process you could be left with obsolete packages, so check for those

sudo apt list '?obsolete'

If any are flagged, they may as well be removed

sudo apt purge '?obsolete'

And it’s worth checking again as I’ve found this can take more than one attempt

sudo apt list '?obsolete'

Similarly, we should check for any configuration files left over

sudo apt list '?config-files'

And remove these if necessary

sudo apt purge '?config-files'

Again, we’ll double check there’s nothing still left

sudo apt list '?config-files'

While we’re here we’ll check for any other leftover configuration files

sudo find /etc -name '*.dpkg-*' -o -name '*.ucf-*' -o -name '*.merge-error'

If there any we may as well remove them, which I did for one computer

sudo rm /etc/ca-certificates.conf.dpkg-old
sudo rm /etc/chrony/chrony.conf.ucf-old

With that done, you can re-install any software you previously removed

But as before, do make sure they are compatible with Trixie first

Summary:
In an ideal world, a fresh installation of an operating system would be preferred

But usually that only happens when it’s time to replace the hardware so it’s more common to upgrade operating systems

As you’ll have seen there is quite a few steps to go through when upgrading to Debian 13, but it’s all to try and make the process as smooth as possible

And although Debian 12 will still be supported for quite some time, an upgrade is necessary if you want newer features and improved performance

Sharing is caring!