Securing VPS/Servers Upgrading

How to Upgrade Debian 12 (Bookworm) to Debian 13 (Trixie)

Upgrade a Debian 12 (bookworm) server to Debian 13 (trixie) in place, step by step, following the upgrade chapter of the official release notes.

This guide upgrades a server from Debian 12 (bookworm) to Debian 13 (trixie), the current stable release, without reinstalling. It follows the upgrade chapter of the official Debian release notes: prepare and back up, switch the APT sources, run the upgrade in two stages, reboot, and clean up.

Older tutorials on this topic covered the move from Debian 6 to Debian 7 (wheezy). Both are long past end of life. The procedure is still recognisably the same, but Debian only supports upgrading from one release to the next. If your server runs Debian 11 or older, upgrade to Debian 12 first and bring it fully up to date, or install Debian 13 fresh and migrate your data.

Before you start

  • Architecture: Debian 13 no longer supports 32-bit PC (i386) as a regular architecture. Do not upgrade an i386 system; reinstall as amd64. Check with dpkg --print-architecture.
  • Space in /boot: if /boot is a separate partition, it should be at least 768 MB with about 300 MB free. Check with df -h /boot.
  • A way back in: make sure you can reach the server through your provider's web console if SSH or networking does not come back after the reboot.
  • Known issues: read the "issues to be aware of" chapter of the Debian 13 release notes for the software you run.

Run the commands as a user with sudo rights, or as root without the sudo prefix.

Step 1: Bring Debian 12 fully up to date

The upgrade is only supported from the latest bookworm point release:

sudo apt update
sudo apt full-upgrade
cat /etc/debian_version

If you are doing this over SSH, check the OpenSSH version:

dpkg -s openssh-server | grep Version

It must be 1:9.2p1-2+deb12u7 or later. Older bookworm versions have an issue that can leave the server unreachable if an upgrade run over SSH is interrupted. If a new kernel was installed, reboot now so you start from a clean state.

Step 2: Check the package state

Look for half-installed packages and for packages on hold, which can make the upgrade fail:

sudo dpkg --audit
apt-mark showhold

Both should print nothing. Release a hold with sudo apt-mark unhold package_name.

List packages that did not come from Debian, and packages that are no longer in any repository:

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

Third-party packages are the most common cause of upgrade trouble. Remove the ones you no longer need, and check that each vendor provides a repository for trixie. Obsolete packages can be removed with sudo apt purge '?obsolete' after you have read the list.

Find leftover configuration files from earlier package upgrades and deal with them:

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

Finally, remove any bookworm-backports and proposed-updates entries from your APT sources, and review any pinning in /etc/apt/preferences and /etc/apt/preferences.d/.

Step 3: Back up

Take a snapshot or full backup of the server if your provider offers one. At minimum, save the configuration and the package database, and copy the archive off the server:

sudo tar czf /root/pre-trixie-backup.tar.gz /etc /var/lib/dpkg /var/lib/apt/extended_states
dpkg --get-selections '*' > ~/package-selections.txt

Back up your databases and site data with their own tools as well. A downgrade from Debian 13 to 12 is not supported, so the backup is your only way back.

Step 4: Prepare services and start a terminal multiplexer

If the server runs MariaDB, stop it cleanly before the upgrade. Crash recovery does not work across the major version change:

sudo systemctl stop mariadb
sudo journalctl -u mariadb -n 20

The log should contain Shutdown complete. If it does not, start the service again so it can recover, then stop it once more and check again.

Stop monitoring tools that restart services on their own, such as monit, for the duration of the upgrade. Then run everything that follows inside tmux (or screen), so a dropped SSH connection does not interrupt the upgrade:

sudo apt install tmux
tmux

If you are disconnected, log in again and run tmux attach.

Step 5: Point APT at trixie

The release notes recommend the deb822 format in /etc/apt/sources.list.d/debian.sources. Look at what you have:

cat /etc/apt/sources.list
ls /etc/apt/sources.list.d/

If debian.sources already exists (common on cloud images), change the suite names in it:

sudo sed -i 's/bookworm/trixie/g' /etc/apt/sources.list.d/debian.sources

If your sources are in /etc/apt/sources.list, move that file aside and create the new one:

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

with this content:

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

Add contrib or non-free to the Components lines only if you used them before. For third-party repositories in /etc/apt/sources.list.d/, either switch them to their trixie suite if the vendor offers one or disable them until the upgrade is finished.

Refresh the package lists:

sudo apt update

Step 6: Check disk space

This command reports how much space the upgrade needs without changing anything:

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

It may end with an error at this stage; what matters is the summary of space required. If you are short, free some with:

sudo apt clean
sudo apt autoremove

Step 7: Run the upgrade in two stages

First the minimal upgrade, which upgrades only packages that need no removals or new installations:

sudo apt upgrade --without-new-pkgs

Then the full upgrade, which installs new dependencies, replaces renamed packages and removes conflicting ones:

sudo apt full-upgrade

During both stages you will be asked whether services may be restarted automatically and what to do with configuration files you have changed. For a modified configuration file, keeping your version (the default answer) is the safe choice; the package's new version is saved next to it with a .dpkg-dist suffix so you can compare later.

If apt full-upgrade stops with an error, these are the documented workarounds:

  • "Could not perform immediate configuration": sudo apt full-upgrade -o APT::Immediate-Configure=0
  • A Conflicts or Pre-Depends loop: sudo apt full-upgrade -o APT::Force-LoopBreak=1
  • Broken dependencies or an interrupted run: sudo dpkg --configure --pending, then sudo apt -f install, then repeat sudo apt full-upgrade

Step 8: Check the kernel and network names, then reboot

Make sure a kernel metapackage is installed, so the new kernel was pulled in and future kernel updates arrive:

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

If nothing is listed on a 64-bit PC system, install it with sudo apt install linux-image-amd64.

Network interface names can change with the new release, which would break networking after the reboot. For each interface (list them with ip -br link), compare the ID_NET_NAME value in the output of this command with the current name:

sudo udevadm test-builtin net_setup_link /sys/class/net/enp1s0 2>/dev/null

If the name differs, update your network configuration to the new name or pin the current one with a systemd.link file before rebooting. If you use encrypted filesystems, confirm that the systemd-cryptsetup package is installed. Then reboot:

sudo systemctl reboot

Step 9: Verify

cat /etc/debian_version
cat /etc/os-release
uname -r
systemctl --failed

The version should start with 13, the kernel should be the new one, and the list of failed units should be empty. Check that your web server, database and other services are running and answering.

Step 10: Clean up

Remove packages that are no longer needed, then review and purge leftover configuration of removed packages and packages that no longer exist in Debian 13:

sudo apt autoremove
apt list '?config-files'
sudo apt purge '?config-files'
apt list '?obsolete'
sudo apt purge '?obsolete'

Read each list before purging. Purging deletes configuration and can delete log files of the affected packages.

If any APT sources are still in the old one-line format, convert them:

sudo apt modernize-sources

Re-enable the third-party repositories you disabled in step 5, pointing them at trixie, and run sudo apt update && sudo apt full-upgrade once more.

Changes you will notice on Debian 13

  • /tmp is a tmpfs: it now lives in memory, limited to 50% of RAM, and is emptied on reboot. An existing /tmp entry in /etc/fstab overrides this. To go back to a disk-based /tmp, run sudo systemctl mask tmp.mount and reboot.
  • /etc/sysctl.conf is no longer read: move your settings to a file in /etc/sysctl.d/, for example /etc/sysctl.d/90-local.conf.
  • OpenSSH: DSA keys are no longer supported, and ~/.pam_environment is no longer read for SSH sessions. Replace DSA keys with ssh-keygen -t ed25519 before upgrading if you still log in with one.
  • last, lastb and lastlog are gone from the base system. Install wtmpdb with libpam-wtmpdb, or lastlog2 with libpam-lastlog2, if you rely on them.

Frequently asked questions

Can I upgrade straight from Debian 11 to Debian 13?

No. Skipping a release is not supported. Upgrade 11 to 12 first, reboot, bring 12 fully up to date, and only then start this guide. With several releases to cross, a fresh installation is often faster and cleaner.

How long does the upgrade take, and is the server down the whole time?

It depends on the number of installed packages, disk speed and your connection. Services are restarted as their packages are upgraded, so expect short interruptions throughout, plus the reboot. Plan a maintenance window and stop services whose data must not change midway, as with MariaDB in step 4.

Should I upgrade in place or reinstall?

An in-place upgrade keeps your configuration and is the supported path for a well-maintained system. Reinstalling is the better choice for an i386 system, a server with many third-party packages, or one whose history you do not trust.

Can I go back to Debian 12 if something breaks?

Not by downgrading packages. Restore the snapshot or backup you made in step 3. That is why the backup step matters more than any other.

Share story:

Continue reading other guides on How VPS.