Upgrading Whonix 15 to Whonix 16

From Whonix

DO NOT USE YET! This page is only for preparation / notes for now. Whonix ™ 16 does not exist yet at all

TODO: remove NOINDEX of this page


Table: Upgrading Whonix Notices

Notice Description
Difficulty Downloading a new Whonix-Gateway ™ / Whonix-Workstation ™ is easier than applying the Release Upgrade instructions on this page, but this process is relatively smooth.
Release Upgrade vs Download

To use Whonix ™ 15, users can either:

Standard Upgrades
Qubes EOL Qubes R4 and above only -- Qubes OS 3.2 has reached End Of Life [archive]. If you are using Qubes R3.2 / R3.2.1, Qubes-Whonix ™ upgrades are unsupported.

High Level Overview[edit]

  1. Backup all data - ideally have a copy of the VM(s) so it is possible to try again (if necessary).
  2. Perform the usual standard ("everyday") upgrade instructions.
  3. Consider running the optional sanity tests.
  4. Release Upgrade Whonix-Workstation ™ (whonix-ws-14).
  5. Power off Whonix-Workstation ™ (whonix-ws-14).
  6. Release Upgrade Whonix-Gateway ™ (whonix-gw-14).
  7. Restart Whonix-Gateway ™ (whonix-gw-14).
  8. Restart Whonix-Workstation ™ (whonix-ws-14).

Sanity Tests[edit]

These are optional, but recommended. To complete sanity tests, please press on expand on the right.

sudo dpkg --audit ; echo $?

Expected output.


sudo dpkg --configure -a ; echo $?

Expected output.


Get package upgrades.

sudo apt-get update

sudo apt-get dist-upgrade

For testing purposes, install python-qt4.

sudo apt-get install python-qt4 ; echo $?

## ... successful installation of python-qt4 ...



First consider completing the sanity tests described above; the system is checked for obvious and grave issues that must be fixed before attempting an upgrade. For example, if the package manager is broken due to the mixing of packages from both Debian stable and Debian testing, then the upgrade may fail part way through, leaving the system in an unstable state that is difficult to resolve.

Consider retaining the full terminal log. Even if the upgrade appears successful, there might be issues following reboot. To properly report a bug in the Whonix ™ forums it is necessary to share the upgrade log so the issue can be investigated.

KDE vs XFCE note: Whonix ™ KDE has been deprecated [archive], meaning Whonix ™ KDE is unsupported from Whonix ™ 15 -- all users should upgrade to Whonix ™ XFCE. These upgrade instructions replace the KDE desktop environment [1] and default applications [2] with those associated with XFCE.

Update Package and Sources Lists[edit]

First upgrade the system's packages by performing the Standard Upgrade Steps. [3]

All Platforms[edit]

Update Whonix ™ apt sources list.

sudo whonix_repository --enable --codename bullseye

Update Debian apt sources list.

sudo sed -i "s/buster/bullseye/g" /etc/apt/sources.list.d/debian.list

Delete the backports, testing and unstable repositories, as well as the default release APT config snippet. [4]

sudo rm -f /etc/apt/sources.list.d/backports.list /etc/apt/sources.list.d/testing.list /etc/apt/sources.list.d/unstable.list /etc/apt/apt.conf.d/70defaultrelease

Qubes-Whonix ™ Only[edit]

Update Qubes' apt sources list.

sudo sed -i "s/buster/bullseye/g" /etc/apt/sources.list.d/qubes*.list


Become root.

sudo su

Enable extensive debugging so the reporting of any eventual bugs is easier.

export DEBDEBUG=1

Update the package lists.

apt-get update


Distribution Upgrade[edit]

To perform a distribution upgrade, it is recommended to run the following command which uses apt-get-noninteractive [archive]; see the footnotes for technical reasons. [5] [6] [7]

Ignore any eventual errors relating to exim* and/or mailx - these packages will be removed in the next step.

apt-get-noninteractive dist-upgrade --no-install-recommends

Purge packages which are not required and broken. On some platforms these packages are not installed, but the step is completely harmless.

apt-get purge exim*

Restart Necessary Services[edit]

Restart whonix-legacy service. [8]

service whonix-legacy restart

Metapackage Installation[edit]

Note: It is possible that the following packages are already installed, but these steps are necessary to confirm it.


  1. In Whonix-Gateway ™, install package non-qubes-whonix-gateway-xfce.
    apt-get install non-qubes-whonix-gateway-xfce

  2. In Whonix-Workstation ™, install package non-qubes-whonix-workstation-xfce.
    apt-get install non-qubes-whonix-workstation-xfce


  1. In Whonix-Gateway ™ (whonix-gw-14), install package qubes-whonix-gateway.
    apt-get install qubes-whonix-gateway

  2. In Whonix-Workstation ™ (whonix-ws-14), install package qubes-whonix-workstation.
    apt-get install qubes-whonix-workstation

Remove Unneeded Packages[edit]

Note: This step is not required for Non-Qubes-Whonix ™ XFCE users.

This long command will remove deprecated meta packages and KDE leftovers; simply cut and paste the entire command. [9] [10]

Run the following command in both Whonix-Gateway ™ and Whonix-Workstation ™.

TODO: none yet

apt-get purge --yes TODO ; \


Remove packages which are no longer required.

apt-get autoremove

Revert to Regular Privileges[edit]

If you are root already (previously became root using sudo su), then exit now.

Open a terminal and run.


Whonix ™ XFCE Desktop Config[edit]

Create folder /home/user/desktop-backup

mkdir -p /home/user/desktop-backup

Reset the XFCE desktop configuration.

mv /home/user/.config/xfce4 /home/user/desktop-backup/

Delete the first-boot-skel.done file. [12]

sudo rm -f /var/cache/anon-base-files/first-boot-skel.done

Execute /usr/lib/anon-base-files/first-boot-skel [archive] to get Whonix ™ XFCE Desktop Config [archive].

sudo /usr/lib/helper-scripts/first-boot-skel

Terminal Log[edit]

Remember to retain the terminal log:

EditSelect AllEditCopyOpen EditorPasteSave

APT Sources Lists[edit]

Open a new terminal window. [13]

Run Whonix ™ APT Repository Tool. [14]

lxsudo whonix-repository-wizard

As explained in step Distribution Upgrade, all system configuration files in /etc were reset to the distributor default. If modifications were previously made to any files in folder /etc/apt/sources.list.d, they should be re-added at this step (if desired).

Review all files in folder /etc/apt/sources.list.d

lxsudo mousepad /etc/apt/sources.list.d/*

If changes were made, follow the standard ("everyday") upgrade instructions.


A reboot is required.

sudo reboot

Start Menu[edit]

The upgrade process does not upgrade the Qubes appmenus (start menu) entries and these must be manually updated. The reason is many applications that were installed by default in Qubes-Whonix ™ 14 are no longer present in Qubes-Whonix ™ 15, due to the change from KDEish to XFCEish default applications. [15]

  1. Qubes appmenuanon-whonixAdd more shortcuts
  2. Qubes appmenusys-whonixAdd more shortcuts
  3. Qubes appmenuwhonix-gw-14Add more shortcuts
  4. Qubes appmenuwhonix-ws-14Add more shortcuts


All necessary steps are now complete.

As a final recommendation, it is advisable to run whonixcheck to check numerous, important system variables. [16]


Testers only! Non-Qubes-Whonix only. XFCE only. Professional Support only.

This would probably brick Qubes-Whonix!

Create a file /usr/lib/release-upgrade with root rights.

lxsudo mousepad /usr/lib/release-upgrade

Paste the following contents. [17]


## Copyright (C) 2020 - 2021 ENCRYPTED SUPPORT LP <>
## See the file COPYING for copying conditions.

set -x
set -e
set -o pipefail

error_handler() {
   local MSG="\
## Something went wrong. Please report this bug!
   echo "$MSG"
   exit 1

trap "error_handler" ERR

if [ "$(id -u)" != "0" ]; then
   true "ERROR: Must run as root."
   true "sudo $0"
   exit 112

if test -e /usr/share/anon-gw-base-files/gateway ; then
elif test -e /usr/share/anon-ws-base-files/workstation ; then
   error "Could not detect gateway or workstation"

export DEBDEBUG=1

dpkg --audit

dpkg --configure -a

rm -f /etc/apt/sources.list.d/derivative.list

sed -i 's/timeout_after="240"/timeout_after="600"/g' /usr/lib/security-misc/apt-get-update

sed -i 's/update \&/update "$@" \&/g' /usr/lib/security-misc/apt-get-update

/usr/lib/security-misc/apt-get-update -o Acquire::Languages=none -o Acquire::IndexTargets::deb::Contents-deb::DefaultEnabled=false

apt-get-noninteractive --yes purge exim* || true

apt-get-noninteractive --yes --no-install-recommends dist-upgrade

apt-get-noninteractive --yes purge exim* || true

apt-get-noninteractive --yes --no-install-recommends install python-qt4

dpkg --audit

dpkg --configure -a

whonix_repository --enable --codename bullseye

sed -i "s/buster/bullseye/g" /etc/apt/sources.list.d/debian.list

rm -f /etc/apt/sources.list.d/backports.list /etc/apt/sources.list.d/testing.list /etc/apt/sources.list.d/unstable.list /etc/apt/apt.conf.d/70defaultrelease

sed -i "s/buster/bullseye/g" /etc/apt/sources.list.d/qubes*.list &>/dev/null || true

/usr/lib/security-misc/apt-get-update -o Acquire::Languages=none -o Acquire::IndexTargets::deb::Contents-deb::DefaultEnabled=false

apt-get-noninteractive dist-upgrade --yes --no-install-recommends

dpkg --audit

dpkg --configure -a

apt-get-noninteractive --yes purge exim* || true

service whonix-legacy restart

apt-get-noninteractive --yes --no-install-recommends install "$pkg"

dpkg --audit

dpkg --configure -a

apt-get-noninteractive --yes purge exim* || true

apt-get-noninteractive purge --yes non-qubes-whonix-gateway || true
apt-get-noninteractive purge --yes non-qubes-whonix-gateway-kde || true
apt-get-noninteractive purge --yes non-qubes-whonix-workstation || true
apt-get-noninteractive purge --yes non-qubes-whonix-workstation-kde || true
apt-get-noninteractive purge --yes whonix-gw-kde-desktop-conf || true
apt-get-noninteractive purge --yes whonix-gw-desktop-shortcuts || true
apt-get-noninteractive purge --yes hardened-desktop-applications-kde || true
apt-get-noninteractive purge --yes hardened-desktop-environment-essential-kde || true
apt-get-noninteractive purge --yes sddm || true
apt-get-noninteractive purge --yes kde-* || true
apt-get-noninteractive purge --yes libkde* || true
apt-get-noninteractive purge --yes qml-module-org-kde-* || true
apt-get-noninteractive purge --yes polkit-kde-agent-1 || true
apt-get-noninteractive purge --yes kded5 || true
apt-get-noninteractive purge --yes *kdelibs* || true
apt-get-noninteractive purge --yes kdesudo || true
apt-get-noninteractive purge --yes ark || true
apt-get-noninteractive purge --yes konsole || true
apt-get-noninteractive purge --yes apt-cacher-ng || true
apt-get-noninteractive purge --yes wpasupplicant || true

if test -e /usr/share/anon-gw-base-files/gateway ; then
   apt-get-noninteractive purge --yes vlc* || true
   apt-get-noninteractive purge --yes libvlc* || true
   apt-get-noninteractive purge --yes phonon* || true

dpkg --audit

dpkg --configure -a

apt-get-noninteractive --yes autoremove

dpkg --audit

dpkg --configure -a

sudo -u user mkdir -p /home/user/desktop-backup || true
sudo -u user mv /home/user/Desktop/*.desktop /home/user/desktop-backup/ || true
sudo -u user mv /home/user/.config/xfce4 /home/user/desktop-backup/ || true

rm -f /var/cache/anon-base-files/first-boot-skel.done || true
/usr/lib/helper-scripts/first-boot-skel || true

unlink /usr/local/etc/onion-grater-merger.d/* || true

rm -f /usr/local/etc/onion-grater-merger.d/40_bisq.yml

sudo sed -i "s#/usr/sbin/tinyproxy#/usr/bin/tinyproxy#g" /lib/systemd/system/qubes-updates-proxy.service &>/dev/null || true

true "OK. Success."


Make executable.

sudo chmod +x /usr/lib/release-upgrade

Run release upgrade script.

sudo /usr/lib/release-upgrade

If everything went well, at the end it will show OK. Success..


  1. Non-Qubes-Whonix only since Qubes-Whonix ™ does not have a desktop environment installed - that is dependent on dom0.
  2. Users have the freedom to retain KDE applications and/or to reinstall those after the upgrade.
  3. Mandatory, not optional for most users. Unless you know what you are doing. This is for example to ensure that the signing key for the next Debian release gets added. Quote debian-archive-keyring changelog [archive]:
    debian-archive-keyring (2019.1+deb10u1) buster; urgency=medium
      * Remove jessie's archive keys (Closes: #981343)
      * Add automatic signing keys for bullseye (Closes: #977911)
      * Update my own key
      * Add Debian Stable Release Key (11/bullseye) (ID: 600062A9605C66F00D6C9793)
        (Closes: #977910)
      * Refresh signatures over keyrings/debian-archive-keyring.gpg and keyrings/debian-archive-removed-keys.gpg
      * Add myself to uploaders
  4. This step is only required if they were previously enabled, but the command is harmless either way.
  5. apt-get-noninteractive prevents the user from being asked difficult technical questions anytime during the upgrade, since the upgrade is stopped until the question is answered. apt-get-noninteractive uses apt-get with -o Dpkg::Options::=--force-confnew. This means apt-get will prefer config files shipped by the distribution in case there is an existing modified config file on the system. Old config files should be automatically moved to configfile.dpkg-old.
  6. Advanced users can use apt-get rather than apt-get-noninteractive. However, it is probably best to use apt-get-noninteractive and to re-apply custom configurations after the upgrade.
  7. Parameter --no-install-recommends prevents the installation of packages (from debian/control Recommends: packages by Debian) which are not useful, confusing or waste disk space inside of virtual machines, such as xscreensaver. For other reasons why Whonix ™ uses --no-install-recommends, see: Technical Stuff.
  8. A manual restart is required because apt-get-noninteractive is being used. This step is not crucial since it would also run after reboot.
  9. In order to separately run the commands, it is necessary to remove the ; and \ characters at the end.
  10. Unfortunately, as of Debian buster apt-get no longer allows a single apt-get purge command followed by a list of all packages. If one of the packages is not already installed, then it aborts the whole command and also refuses to uninstall those which are still present. Therefore, to run commands in succession the ; parameter is used, while \ allows a single long command to be split into multiple lines for better readability.
  11. VM XFCE is not being used in Qubes and package Whonix ™ XFCE Desktop Config [archive] is also not installed, so this step is unnecessary. If you want to apply this anyhow, it should be done in every AppVM.
  12. So it can be re-run.
  13. Because GUI application whonix-repository-wizard should not be run as root.
  14. To select the correct APT repository for use.
  15. [archive]
  16. The following message is not a concern.
    The following packages were automatically installed and are no longer required:
      hardened-packages-recommended-cli non-qubes-vm-enhancements-gui whonix-workstation-default-applications-gui whonix-ws-desktop-shortcuts

text=Jobs in USA
Jobs in USA

Search engines: YaCy | Qwant | ecosia | MetaGer | peekier | Whonix ™ Wiki

Follow: 1024px-Telegram 2019 Logo.svg.png Iconfinder Apple Mail 2697658.png Twitter.png Facebook.png Rss.png Reddit.jpg 200px-Mastodon Logotype (Simple).svg.png

Support: 1024px-Telegram 2019 Logo.svg.png Discourse logo.png Matrix logo.svg.png

Donate: Donate Bank Wire Paypal Bitcoin accepted here Monero accepted here Contriute

Whonix donate bitcoin.png Monero donate Whonix.png United Federation of Planets 1000px.png

Twitter-share-button.png Facebook-share-button.png Telegram-share.png link=mailto:?subject=Upgrading Whonix 15 to Whonix 16&body= link= Whonix 15 to Whonix 16 link= Whonix 15 to Whonix 16 link= Whonix 15 to Whonix 16%20 Whonix 15 to Whonix 16

Did you know that Whonix ™ could provide protection against backdoors? See Verifiable Builds. Help is wanted and welcomed.

https link onion link

This is a wiki. Want to improve this page? Help is welcome and volunteer contributions are happily considered! Read, understand and agree to Conditions for Contributions to Whonix ™, then Edit! Edits are held for moderation. Policy of Whonix Website and Whonix Chat and Policy On Nonfreedom Software applies.

Copyright (C) 2012 - 2021 ENCRYPTED SUPPORT LP. Whonix ™ is a trademark. Whonix ™ is a licensee [archive] of the Open Invention Network [archive]. Unless otherwise noted, the content of this page is copyrighted and licensed under the same Freedom Software license as Whonix ™ itself. (Why?)

The personal opinions of moderators or contributors to the Whonix ™ project do not represent the project as a whole.

Whonix ™ is a derivative of and not affiliated with Debian [archive]. Debian is a registered trademark [archive] owned by Software in the Public Interest, Inc [archive].

Whonix ™ is produced independently from the Tor® [archive] anonymity software and carries no guarantee from The Tor Project [archive] about quality, suitability or anything else.

By using our website, you acknowledge that you have read, understood and agreed to our Privacy Policy, Cookie Policy, Terms of Service, and E-Sign Consent. Whonix ™ is provided by ENCRYPTED SUPPORT LP. See Imprint, Contact.

By using our website, you acknowledge that you have read, understood and agreed to our Privacy Policy, Cookie Policy, Terms of Service, and E-Sign Consent.