Upgrade Ubuntu or Debian to a new release

Every release reaches the end of its free security updates, so a server that runs for years needs a release upgrade now and then. Ubuntu's do-release-upgrade and Debian's documented apt procedure upgrade the system in place: same server, same IP address, same data. This guide follows the official procedures.

Before you start

• Check the path. Ubuntu upgrades from one LTS to the next LTS (22.04 → 24.04 → 26.04). Debian 13 supports upgrades only from Debian 12. See Ubuntu's release cycle for support dates.
• Back up your data and configuration, and test that you can restore it; see backup strategy. If your plan includes snapshots, take one as well.
• Plan a maintenance window. Services restart during the upgrade and the server reboots at the end.
• Know your console. If the network does not come up after the reboot, you need the server's console; see server unreachable.
• Free space: the upgrade downloads several hundred packages. Keep a few gigabytes free on / and enough on /boot.
• Read the release notes of the target release for software you run (databases, PHP, Python).

Upgrade Ubuntu to the next LTS

Step 1: Bring the current release fully up to date

sudo apt update
sudo apt dist-upgrade -o APT::Get::Always-Include-Phased-Updates=true

Both must finish without errors. If the file /run/reboot-required exists, reboot and connect again:

ls /run/reboot-required && sudo reboot

Step 2: Run the upgrade

sudo do-release-upgrade

The tool runs its checks, shows a summary and asks Continue [yN] before it changes anything. Third-party repositories (PPAs and vendor repositories) are disabled during the upgrade; note which ones you use so you can turn them back on later.

When a configuration file you changed differs from the new package's version, you are asked what to do: N or O keeps your file (the default), Y or I installs the new one, D shows the differences. Keep your file unless you know the new default is needed. Remove obsolete packages when asked, then reboot when prompted: the upgrade is not complete until the server has restarted.

Step 3: Check the result

lsb_release -a
sudo apt update && sudo apt upgrade

Upgrade Debian 12 to Debian 13

Step 1: Prepare Debian 12

Bring Debian 12 up to date, then check for broken or held packages and for packages that do not come from Debian:

sudo apt update && sudo apt full-upgrade
cat /etc/debian_version
sudo dpkg --audit
apt-mark showhold
apt list '?narrow(?installed, ?not(?origin(Debian)))'

dpkg --audit must print nothing. Remove holds you no longer need and plan what to do with the non-Debian packages. Save the package selection for reference:

dpkg --get-selections '*' > ~/curr-pkgs.txt

Step 2: Point APT at Debian 13

The release notes describe one file in the deb822 format. Create /etc/apt/sources.list.d/debian.sources with sudo nano:

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

Then disable the old entries: remove /etc/apt/sources.list (or put # in front of every bookworm line) and any other Debian files under /etc/apt/sources.list.d/.

Step 3: Upgrade in two stages

Refresh the lists and check the disk space the upgrade needs:

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

Then run the minimal upgrade first and the full upgrade second:

sudo apt upgrade --without-new-pkgs
sudo apt full-upgrade

Answer configuration questions as described for Ubuntu above. Make sure a kernel metapackage is installed before you reboot (dpkg -l 'linux-image*' | grep ^ii), then reboot.

Step 4: Check and clean up

cat /etc/debian_version
sudo apt autoremove
sudo apt modernize-sources

apt modernize-sources converts any remaining old-format source files to the deb822 format.

Check your services

Verify: the server boots into the new release, your services run (systemctl --failed lists nothing), your sites and applications respond, and sudo apt update shows no errors. Turn third-party repositories back on with their releases for the new system.

Troubleshooting

No new release found (Ubuntu). The current release is not up to date yet (repeat Step 1 and reboot), or the next LTS has no point release yet. sudo do-release-upgrade -c only checks whether a new release is available.

The upgrade stopped halfway. Reconnect, attach to tmux if you used it, otherwise run sudo dpkg --configure -a and sudo apt full-upgrade; see fix apt and dpkg errors.

Could not perform immediate configuration (Debian). The release notes give this workaround: sudo apt full-upgrade -o APT::Immediate-Configure=0.

A service fails after the reboot. Read its log with sudo journalctl -u service-name -b and compare its configuration file with the new package default, which apt saves next to yours with a suffix such as .dpkg-dist or .ucf-dist.

The server is unreachable after the reboot. Open the console and check ip -brief address and systemctl status networking systemd-networkd; see server unreachable.

Next steps

• Keep the new release patched: automatic updates.
• Starting over is sometimes faster: reinstall the operating system.