How to upgrade a Debian template in-place

Warning

This page is intended for advanced users.

Most users will find it easier to install a new template instead of upgrading in-place. If you have made customizations or installed additional packages in the current template that you want to preserve, then upgrading in-place may be the best way to go.

This page provides instructions for performing an in-place upgrade of an installed Debian Template. In general, upgrading a Debian template follows the same process as upgrading a native Debian system.

Note

In what follows the prompt on each line indicates where each command should be entered: dom0, debian-<old>, or debian-<new>, where <old> is the Debian version number from which you are upgrading, and <new> is the Debian version number to which you are upgrading. Remember to use the right template version: eg clone debian-<old>-minimal to debian-<new>-minimal.

By default, Qubes uses code names in the apt sources files (bookworm, trixie, etc), although the templates are referred to by release number. Check the code names for the templates, and ensure you are aware of any changes you have made in the repository definitions.

Summary instructions for Debian templates

[user@dom0 ~]$ qvm-clone debian-<old> debian-<new>
[user@dom0 ~]$ qvm-run debian-<new> qubes-run-terminal &
[user@debian-<new> ~]$ sudo apt update
[user@debian-<new> ~]$ sudo apt upgrade
[user@debian-<new> ~]$ sudo sed -i 's/<old-name>/<new-name>/g' /etc/apt/sources.list
[user@debian-<new> ~]$ sudo sed -i 's/<old-name>/<new-name>/g' /etc/apt/sources.list.d/qubes-r4.list
[user@debian-<new> ~]$ sudo apt update
[user@debian-<new> ~]$ sudo apt upgrade
[user@debian-<new> ~]$ sudo apt dist-upgrade
[user@dom0 ~]$ qvm-shutdown debian-<new>
[user@dom0 ~]$ qvm-features  debian-<new> template-name debian-<new>

Detailed instructions for Debian templates

These instructions will show you how to upgrade Debian templates. The same general procedure may be used to upgrade any template based on the standard Debian templates.

Ensure the existing template is not running.

[user@dom0 ~]$ qvm-shutdown debian-<old>

Clone the existing template and start a terminal in the new template.

[user@dom0 ~]$ qvm-clone debian-<old> debian-<new>
[user@dom0 ~]$ qvm-run debian-<new> qubes-run-terminal

Update the new cloned template.

[user@debian-<new> ~]$ sudo apt update
[user@debian-<new> ~]$ sudo apt upgrade

Update your apt repositories to use the new release’s code name instead of the old release’s code name. (This can be done manually with a text editor, but sed can be used to automatically update the files.)
```
[user@debian-<new> ~]$ sudo sed -i 's/<old-name>/<new-name>/g' /etc/apt/sources.list
[user@debian-<new> ~]$ sudo sed -i 's/<old-name>/<new-name>/g' /etc/apt/sources.list.d/qubes-r4.list
```
Update the package lists and upgrade. During the process, it may prompt you to overwrite the file qubes-r4.list. You should overwrite this file.
```
[user@debian-<new> ~]$ sudo apt update
[user@debian-<new> ~]$ sudo apt upgrade
[user@debian-<new> ~]$ sudo apt dist-upgrade
```
(Optional) Remove unnecessary packages that were previously installed.
```
[user@debian-<new> ~]$ sudo apt-get autoremove
```
(Optional) Clean cached packages from /var/cache/apt.
```
[user@debian-<new> ~]$ sudo apt-get clean
```

(Optional) Trim the new template. (This should no longer be necessary, but it does not hurt. Some users have reported that it makes a difference.)

[user@debian-<new> ~]$ sudo fstrim -av
[user@dom0 ~]$ qvm-shutdown debian-<new>
[user@dom0 ~]$ qvm-start debian-<new>
[user@debian-<new> ~]$ sudo fstrim -av

Shut down the new template.

[user@dom0 ~]$ qvm-shutdown debian-<new>

Set the template-name, which is used by the Qubes updater.

[user@dom0 ~]$ qvm-features debian-<new> template-name debian-<new>

(Recommended) Switch everything that was set to the old template to the new template.

(Optional) Make the new template the global default.

[user@dom0 ~]$ qubes-prefs --set default_template debian-<new>

(Optional) Uninstall the old template. Make sure that the template you’re uninstalling is the old one, not the new one!

Note

If you installed packages from one of the testing repositories, you must make sure that the repository is enabled in /etc/apt/sources.list.d/qubes-r4.list before attempting the upgrade. Otherwise, your upgrade will break.

Standalones

The procedure for upgrading a Debian standalone is the same as for a template.

End-of-life (EOL) releases

We strongly recommend against using any Debian release that has reached end-of-life (EOL).