A major Debian upgrade is more than changing a repository name. APT may replace core packages, restart services, and remove packages to resolve dependencies. If the machine is remote, a mistake can also leave you without SSH access.
For Debian 12 (Bookworm) to Debian 13 (Trixie), the safer sequence is: prepare recovery, fully update Bookworm, change supported Debian sources, run the upgrade in two stages, then reboot and verify.
Before changing anything
Start with a backup or VM snapshot you know how to restore. If this is a remote server, confirm that you can reach its provider console or another out-of-band recovery method. A persistent terminal session such as tmux or screen, if installed, can help if your SSH connection drops—but it is not a substitute for recovery access.
Check the installed release, available space, and package holds:
cat /etc/os-release
df -h / /var /boot
apt-mark showhold
Pay particular attention to /boot if it is a separate, small filesystem. A new kernel and initramfs need room. This guide to checking disk space on Linux explains how to investigate capacity before an upgrade.
Review held packages and locally installed software that depends on third-party repositories. A hold may be intentional; don’t remove it without understanding why. Check that critical vendor packages support Debian 13.
Bring Bookworm fully up to date
Do not switch releases while Bookworm still has unexplained pending updates or dependency problems. First update the current release:
sudo apt update
sudo apt upgrade
Review APT’s proposed changes before confirming. Resolve errors or held-package conflicts while the machine is still on Debian 12. If a kernel or other core package was updated, reboot if appropriate, then verify the system is healthy before continuing.
Run commands without sudo if you are already in a root shell.
Update the right APT sources
Debian repository definitions can be in /etc/apt/sources.list, files under /etc/apt/sources.list.d/, or both. Newer installations may use deb822 files ending in .sources, where the release appears in a Suites: field rather than a deb line.
Find files mentioning Debian release names:
grep -RInE 'bookworm|bullseye|trixie' \
/etc/apt/sources.list /etc/apt/sources.list.d 2>/dev/null
Inspect the results individually. For Debian repositories, change the relevant Bookworm suite to Trixie while preserving the repository URL, components, and other applicable settings. Review security and updates entries too. Don’t blindly replace every occurrence of bookworm: a third-party vendor may not provide a Trixie repository, and changing its suite name does not make it compatible.
Make a copy of source files before editing. Temporarily disable third-party sources if their Debian 13 support is unclear, and keep notes so you can revisit them later.
After editing, check that the active Debian entries point to the intended release and that no unintended older-release entries remain. If the source layout is confusing, stop and consult the official Debian 13 upgrade notes rather than guessing.
Run the upgrade in two stages
Refresh package lists first:
sudo apt update
Do not continue if this reports missing Release files, signature errors, or other repository failures. Fix the source definitions before installing packages.
Then perform the minimal upgrade:
sudo apt upgrade --without-new-pkgs
Read the proposed package plan. This step upgrades packages where possible without installing new packages or removing packages to resolve dependency changes. Pause if APT proposes removing essential software or making changes you don’t understand.
Next, complete the transition:
sudo apt full-upgrade
Unlike a plain apt upgrade, full-upgrade can install new dependencies and remove packages when needed. Review removals carefully before accepting. During the upgrade, configuration prompts may ask whether to keep a locally modified file or install the package maintainer’s version. Compare the options; preserving a custom SSH, network, or service configuration may be important.
Keep the terminal open until APT finishes. If the session disconnects, check whether the package operation is still running before starting another one. Don’t reboot in the middle of an active package operation.
Reboot and verify
Once APT finishes without errors, reboot when you have an appropriate maintenance window:
sudo reboot
After the server returns, check the release, running kernel, and package sources:
cat /etc/os-release
uname -r
sudo apt update
apt list --upgradable
/etc/os-release should identify Debian GNU/Linux 13, also known as Trixie. uname -r shows the kernel currently running; it can differ from a newly installed kernel if the reboot did not complete as expected.
Check SSH access, networking, scheduled jobs, and the applications that matter on this machine. For systemd services, inspect their status and logs if anything failed. If SSH itself needs attention, use a safe sequence to restart the SSH service on Linux rather than assuming a restart will solve every connection issue.
Re-enable third-party repositories only after confirming that the vendor supports Trixie. Then check whether the software needs a separate upgrade or migration step.
If something goes wrong
If apt update fails, inspect both .list and .sources files for typos, mixed Debian releases, or unsupported vendor entries. Don’t proceed with a broken repository state.
If an upgrade was interrupted, first establish whether APT or dpkg is still running. Once no package manager process is active, these commands can help recover an interrupted configuration or dependency operation:
sudo dpkg --configure -a
sudo apt --fix-broken install
Review their proposed changes; stop if they suggest removals you did not expect. Don’t delete package locks or force-remove unfamiliar packages as a shortcut.
If the machine no longer boots or SSH is unreachable, use the provider console or recovery environment and follow your backup plan. For a remote server, that recovery path is part of the upgrade preparation—not something to figure out after access is lost.
I originally published a more detailed version of this guide on the SSHFlow blog.
I'm also building SSHFlow — an SSH client where every server gets its own workspace for terminals, SFTP, code, and databases.
Top comments (1)
Official Platform Update
Security protocols have been updated for all developer accounts.