General advice for upgrading Debian. For guidance about upgrading to a specific version, see Debian 12 (bookworm) Release Notes or Debian 13 (trixie) Release Notes. For other up/downgrade topics, see Install, remove, and change software versions.
Contents
Back your data up before upgrading
Upgrading your system is never without risk. Even if you do everything right, the volume of disk activity could prove your disk was nearer to end-of-life than you realised.
Before upgrading, copy all your personal data (at minimum the contents of /home) to a disk that can remain disconnected and in a drawer while you upgrade. Consider taking the opportunity to make a monthly backup schedule, in case your disk is only slightly nearer to end-of-life than you realise.
For more information about what to back up, see DebianStability.
Ensure cryptsetup-initramfs remains installed
If you use an encrypted root filesystem, make sure cryptsetup-initramfs stays installed:
apt-mark manual cryptsetup-initramfs
cryptsetup-initramfs ensures disk encryption support is available in the initramfs that mounts the root filesystem. If cryptsetup-initramfs was originally installed as a dependency when you were installing some other package, and the new version of that package drops the dependency, apt might think you're not using cryptsetup-initramfs and decide to remove it. The command above marks it as being manually installed, so apt knows to keep it.
Create a rescue device
If something goes wrong and your system won't boot, a rescue device lets you boot another system and fix the problem. You might like to use a dedicated rescue system, a Debian Live image, or just a normal Linux system installed on a memory stick instead of a hard drive.
Before upgrading Debian, check you can boot your rescue device from your computer, and that the rescue device itself is upgraded to the latest version.
Do a trial run in QEMU
If you're expecting a particularly difficult upgrade, you can upgrade a temporary copy of your system in a virtual machine, and only commit your changes when you've confirmed everything's OK.
Boot to your rescue device
You can't run your system on your actual machine and a virtual machine at the same time, so boot to your rescue device instead.
Make sure qemu-system-x86 (or the equivalent for your architecture) is installed on your rescue device, so it can run your main system in a virtual machine.
Create a disk image backed by your physical disk
Qemu lets you create a disk image that's backed by your physical disk. That means it starts off reading from your physical disk, but it writes changes to the image instead of the disk. So upgrades are applied safely to the image until you explicitly commit them to the physical disk.
First, work out what name your rescue system has given to your physical disk:
sudo blockdev --report /dev/disk/by-id/* | grep -v -- -part[0-9]*$ | sort -n -k6
You should see a list of devices, with the size of the device and some technical information. Your physical disk could be any of these, but is probably the one with the highest size and a name that begins with /dev/disk/by-id/ata-. When you've decided which disk to use, make a variable to remember it:
TARGET_DEVICE="/dev/disk/by-id/ata-<whatever>"
Next, check whether any partitions on your target are currently mounted:
grep "$(readlink -f "$TARGET_DEVICE")" /proc/mounts
If the command doesn't say anything, you're safe to continue. If it says something like /dev/sda1 /media/user/EFI ..., unmount /media/user/EFI and repeat the previous command until you run out of mount-points. If it says something like /dev/sda1 / ..., you've picked the wrong disk - try another one from the blockdev list.
Finally, create a disk image backed by your target device:
sudo qemu-img create -f qcow2 ~/hd_image.qcow2 -F raw -b "$TARGET_DEVICE"
the command above creates a disk image in your rescue device's home directory. If your computer has a lot of memory (>10GB), your rescue device is running at least trixie and has a slow disk, change ~/hd_image.qcow2 to /tmp/hd_image.qcow2 to use an in-memory temporary file instead.
Boot your machine in a VM
Run this command (or the equivalent for your architecture):
sudo qemu-system-x86_64 \
-m 1G -cpu max -enable-kvm \
-device virtio-net-pci,netdev=net0 \
-netdev user,id=net0,hostfwd=tcp::2222-:22 \
-drive file=~/hd_image.qcow2,cache=unsafe
Your main system should boot up in a window! If the program refuses to run until you remove -enable-kvm, you may need to enable virtualization in your BIOS.
cache=unsafe means shutting the VM down incorrectly can corrupt ~/hd_image.qcow2, but we can just throw it away and start over if that happens.
To prove that changes to this VM are not applied to your actual machine, make some small change (e.g. create a new empty file), shut the computer down, delete and recreate ~/hd_image.qcow2, then restart the VM again. The new file should no longer exist.
If you run an ssh server on your main system, you should be able to connect to your VM with ssh -p 2222 localhost.
Upgrade your machine in a VM
You now have a simulation of your main system running in a virtual machine, and changes in the VM aren't saved to your physical disk. Upgrade your main system in the normal way, making notes of anything you need to do during the process. See for example Upgrading from One Stable Distribution to the Next in The Debian Administrator's Handbook.
Once you've finished the upgrade, reboot the VM and make sure your system works. It should still boot up, your programs should still work, your files should all be there, and so on. If not, never mind - just shut the VM down, delete and recreate ~/hd_image.qcow2, and try again.
Commit changes to your physical disk (optional)
Once you've upgraded successfully, ~/hd_image.qcow2 will contain all the changes you need to make. You can update your target device by saving those changes to disk:
sudo qemu-img commit -p ~/hd_image.qcow2
This might take a while to complete, but cancelling it will corrupt your target device. If your computer is a laptop, make sure it's plugged in before you start!
If you trust your notes more than you trust qemu-img, you might prefer to treat this all as a dry run - throw the file away, reboot into your main system and upgrade the old-fashioned way.
See also
DontBreakDebian discusses some things that can cause upgrades to fail
DebianInstaller/Qemu discusses installing a new system in a VM
CrossGrading discusses upgrading from e.g. i386 to x86_64