Upgrading Whonix 14 to Whonix 15

From Whonix


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.

All Platforms[edit]

Update Whonix ™ apt sources list.

sudo whonix_repository --enable --codename buster

Update Debian apt sources list.

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

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

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/stretch/buster/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. [4] [5] [6]

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. [7]

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. [8] [9]

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

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

The following packages should be purged on Whonix-Gateway ™ only.

apt-get purge --yes vlc* ; \
apt-get purge --yes libvlc* ; \
apt-get purge --yes phonon*


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.


Remove Desktop Shortcuts[edit]

Desktop shortcuts are no longer supported by Whonix ™ developers. [11]

Create folder /home/user/desktop-backup

mkdir -p /home/user/desktop-backup

Move any obsolete .desktop files to a backup folder. Make sure no extra spaces are added to the following command!

mv /home/user/Desktop/*.desktop /home/user/desktop-backup/

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. [13]

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


Only complete the following steps if any applications were used that required an onion-grater whitelist extension, such as OnionShare, ZeroNet, Ricochet IM and Bisq:

First remove all existing onion-grater extension profiles.

sudo unlink /usr/local/etc/onion-grater-merger.d/* ; echo "$?"

If it shows unlink: cannot unlink '/usr/local/etc/onion-grater-merger.d/*': No such file or directory, then no onion-grater profiles existed before -- move on to the next chapter.

If it shows 0, this means some onion-grater profiles were deactivated. It is necessary to reactivate them using updated instructions:

Next, delete the eventual /usr/local/etc/onion-grater-merger.d/40_bisq.yml onion-grater extension profile.

sudo rm /usr/local/etc/onion-grater-merger.d/40_bisq.yml ; echo "$?"

If it shows rm: cannot remove '/usr/local/etc/onion-grater-merger.d/40_bisq.yml': No such file or directory, then no Bisq onion-grater profile existed before -- move on to the next chapter.

If it shows 0 this means that Bisq onion-grater profile was deactivated. It is necessary to reactivate it using updated instructions:


Qubes-Whonix ™ Whonix-Gateway ™ (whonix-gw-14) only!

Fix tinyproxy path. [14]

sudo sed -i "s#/usr/sbin/tinyproxy#/usr/bin/tinyproxy#g" /lib/systemd/system/qubes-updates-proxy.service

Terminal Log[edit]

Remember to retain the terminal log:

EditSelect AllEditCopyOpen EditorPasteSave

APT Sources Lists[edit]

Open a new terminal window. [15]

Run Whonix ™ APT Repository Tool. [16]

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. [17]

  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. [18]


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.

kdesudo mousepad /usr/lib/release-upgrade

Paste the following contents. [19]


## 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/whonix.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 buster

sed -i "s/stretch/buster/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/stretch/buster/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. This step is only required if they were previously enabled, but the command is harmless either way.
  4. 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.
  5. 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.
  6. 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.
  7. A manual restart is required because apt-get-noninteractive is being used. This step is not crucial since it would also run after reboot.
  8. In order to separately run the commands, it is necessary to remove the ; and \ characters at the end.
  9. 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.
  10. Desktop shortcuts are not visible in Qubes, so this step is unnecessary. If you want to apply this anyhow, then it should be done in every AppVM.
  11. Due to issues with XFCE.
  12. 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.
  13. So it can be re-run.
  14. [archive]
  15. Because GUI application whonix-repository-wizard should not be run as root.
  16. To select the correct APT repository for use.
  17. [archive]
  18. 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

Fosshost is sponsors Kicksecure stage server Whonix old logo.png
Fosshost About Advertisements

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 14 to Whonix 15&body= link= Whonix 14 to Whonix 15 link= Whonix 14 to Whonix 15 link= Whonix 14 to Whonix 15%20 Whonix 14 to Whonix 15

We are looking for contributors and developers.

https link onion link Priority Support | Investors | Professional Support

Whonix | © ENCRYPTED SUPPORT LP | Heckert gnu.big.png Freedom Software / Osi standard logo 0.png Open Source (Why?)

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

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.