Debian 13 "Trixie" has been stable since August 2025. If you're still running Debian 12 "Bookworm", it's a great time to upgrade. This guide walks you through the entire process step by step, no advanced Linux knowledge required.
1. Pre-Upgrade Checklist
1.1. Back up your data
This is the most important step. If you have the option to take snapshots (if your hosting provider supports), do it now. If not, back up your critical data, such as databases, config files, websites, and application data.
1.2. Check your disk space
Run the following command to make sure you have enough free space. You'll typically need at least 2–3 GB free on / for the upgrade.
df -h /
1.3. Note your current kernel and Debian version
This gives you a reference point if you need to troubleshoot later.
uname -r
cat /etc/debian_version
1.4. Review third-party repositories
If you've added repos for things like Docker, Node.js, or PostgreSQL, you may need to update or temporarily disable them. Check what's configured:
cat /etc/apt/sources.list
ls /etc/apt/sources.list.d/
It's a good idea to temporarily disable third-party repos (comment them out or rename the files) and re-enable them with Trixie-compatible versions after the upgrade.
1.5. Make sure Debian 12 is fully up to date
Never try to jump to a new major version from an outdated system.
sudo apt update
sudo apt upgrade -y
sudo apt full-upgrade -y
sudo apt autoremove -y
1.6. Use a terminal multiplexer
If you're connected via SSH, run everything inside screen or tmux. That way, if your SSH connection drops mid-upgrade, the process keeps running in the background.
sudo apt install screen -y
screen
If you get disconnected, reconnect to your server and run screen -r to reattach.
2. Step-by-Step Upgrade Process
2.1. Update Your Package Sources
The key to a Debian major version upgrade is simply pointing your package sources from bookworm to trixie. Run this command:
sudo sed -i 's/bookworm/trixie/g' /etc/apt/sources.list
If your system uses the newer DEB822 .sources format (common on recent Debian 12 installs), update those files too:
sudo sed -i 's/bookworm/trixie/g' /etc/apt/sources.list.d/*.sources 2>/dev/null
sudo sed -i 's/bookworm/trixie/g' /etc/apt/sources.list.d/*.list 2>/dev/null
Quickly verify your sources look correct:
cat /etc/apt/sources.list
You should see trixie where bookworm used to be. The security.debian.org lines should now reference trixie-security.
2.2. Refresh the Package Index
sudo apt update
This downloads the package lists for Debian 13. You might see a few warnings about changed repository signatures, that's normal during a major version upgrade.
2.3. Perform the Upgrade
This happens in two stages. First, a minimal upgrade:
sudo apt upgrade -y
This upgrades packages that don't require removing or installing other packages. Then, run the full upgrade:
sudo apt full-upgrade -y
full-upgrade (formerly dist-upgrade) is the important one, it handles all the complex dependency changes, removes obsolete packages, and installs new required ones.
During the upgrade, you may be asked about configuration files. The prompt will look something like:
Configuration file '/etc/some/config'
==> Modified (by you or by a script) since installation.
==> Package distributor has shipped an updated version.
What would you like to do about it?
Here's a simple rule of thumb:
- If you haven't customized the file → choose "install the package maintainer's version"
- If you have customized it → choose "keep your currently-installed version" and manually merge changes later
2.4. Clean Up
Remove packages that are no longer needed:
sudo apt autoremove -y
sudo apt autoclean
2.5. Reboot
sudo reboot
2.6. Verify the Upgrade
After the reboot, log back in and confirm:
cat /etc/debian_version
lsb_release -a
uname -r
You should see version 13.x and a new kernel version.
Congratulations, you're on Debian 13 Trixie!
3. Troubleshooting Tips
Things don't always go perfectly. Here are the most common issues and how to fix them.
• Packages have unmet dependencies
This usually happens when third-party repos are still pointing to Bookworm. Disable them, run sudo apt update, and try the upgrade again.
# Temporarily move third-party sources aside
sudo mv /etc/apt/sources.list.d/docker.list /etc/apt/sources.list.d/docker.list.bak
sudo apt update
sudo apt full-upgrade -y
• The upgrade seems stuck or frozen
If you're in a screen or tmux session, the upgrade is likely still running, just be patient. Some package installations (like kernel or GRUB updates) can take a while. Don't interrupt the process.
• GRUB bootloader prompt
If you're asked where to install GRUB, select the same disk your system currently boots from (usually /dev/sda or /dev/vda). If you're unsure:
lsblk
Look for the disk that has your root (/) partition.
• SSH connection refused after reboot
The SSH config may have been replaced during the upgrade. If you have console access, check:
sudo systemctl status ssh
sudo nano /etc/ssh/sshd_config
Make sure PermitRootLogin and Port are set to your preferred values. Restart SSH:
sudo systemctl restart ssh
• Services not starting after reboot
Check which services failed:
sudo systemctl --failed
Then review logs for the specific service:
sudo journalctl -u <service-name> --no-pager -n 50
4. Rollback Instructions
1. Restore from Snapshot
If you took a snapshot before starting, this is by far the easiest path. Simply restore the snapshot through your hosting provider's control panel. Everything will be exactly as it was before the upgrade.
4.2 Downgrade Sources (Last Resort)
Warning: Downgrading a Debian system is not officially supported and can leave your system in a broken state. Only attempt this if you have no other option.
4.2.1. Change your sources back to Bookworm:
sudo sed -i 's/trixie/bookworm/g' /etc/apt/sources.list
sudo sed -i 's/trixie/bookworm/g' /etc/apt/sources.list.d/*.sources 2>/dev/null
sudo sed -i 's/trixie/bookworm/g' /etc/apt/sources.list.d/*.list 2>/dev/null
4.2.2. Update and attempt to downgrade:
sudo apt update
sudo apt install --reinstall $(dpkg --get-selections | awk '{print $1}') 2>/dev/null
This is messy and likely won't fully work. The real lesson here: always take a backup before upgrading.
5. Final Thoughts
Upgrading from Debian 12 to Debian 13 is straightforward when you prepare properly. The process boils down to: back up, update your sources, run the upgrade, and reboot. The whole thing usually takes under an hour.
The most important takeaway? Always have a backup. Everything else is fixable.
