Upgrade Debian to a new version

November 07, 2026

When moving to a new Debian version, we have two goals:

Here are the steps:

Edit /etc/apt/source.list and change the distribution code name and run apt update

Hold back the packages for the critical services. For example, on a mailstore server, hold back postfix and dovecot with:

apt-mark hold postfix dovecot-core

On a MySQL server:

apt-mark hold mariadb-common

You typically only need to pick one package in a package family to hold them all back.

Run the upgrade

apt dist-upgrade -y -o Dpkg::Options::="--force-confdef" -o Dpkg::Options::="--force-confnew"

force-confdef: Automatically chooses the default action if you haven’t modified the configuration file locally.
force-confnew: Automatically accepts the package maintainer’s new version if your local file has been modified.

Sometimes the upgrade step will fail if we ran out of room on /boot - running autoremove will clear out un-needed kernels and free up space.

apt autoremove

To unhold the packages you held:

apt-mark unhold mariadb-common

And then re-run:

apt dist-upgrade -y -o Dpkg::Options::="--force-confdef" -o Dpkg::Options::="--force-confnew"

Lastly, run apt update again to ensure you get the message that no packages are available for upgrade.

Run ansible with --secrets to ensure all settings are up to date:

sower --live playbook --secrets $server.mayfirst.org

This step ensures all the configuration files for which we took the maintainer’s version get updated as necessary.

All done! systemctl poweroff