Last update: March 17, 2019. This website uses cookies. 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. More information


Upgrading Whonix 14 to Whonix 15


Note: Whonix 15 is currently recommended for testers only.

Table: Upgrading Whonix Notices

Notice Description
Qubes EOL Qubes R4 and above only -- Qubes OS 3.2 has reached End Of Life. If you are using Qubes R3.2 / R3.2.1, Qubes-Whonix ™ upgrades are unsupported.
Release Upgrade Method Downloading a new Whonix-Gateway ™ / Whonix-Workstation ™ is easier than applying the following upgrade instructions, but this process is relatively smooth.
Release Upgrade: Non-Qubes-Whonix ™ vs Qubes-Whonix ™

To use Non-Qubes-Whonix ™ 15, users can either:

  • Upgrade existing Whonix ™ 14 images; or
  • Re-install Whonix ™ by downloading the new release, which is much simpler than upgrading; see VirtualBox Testers Only Version.

To use Qubes-Whonix ™ 15:

Standard Upgrades

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, meaning Whonix ™ KDE is unsupported from Whonix ™ 15 -- all users should upgrade to Whonix ™ XFCE. These upgrade instructions replace the KDE desktop environment [2] and default applications [3] 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. [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/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; 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 ™.

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

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

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

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

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

sudo /usr/lib/anon-base-files/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. [15]

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:

Edit -> Select All -> Edit -> Copy -> Open Editor -> Paste -> Save

APT Sources Lists[edit]

Open a new terminal window. [16]

Run Whonix ™ APT Repository Tool. [17]

lxsu 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

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

  1. Qubes appmenu -> anon-whonix -> Add more shortcuts
  2. Qubes appmenu -> sys-whonix -> Add more shortcuts
  3. Qubes appmenu -> whonix-gw-14 -> Add more shortcuts
  4. Qubes appmenu -> whonix-ws-14 -> Add more shortcuts


All necessary steps are now complete.

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


  1. Blocker: create Debian buster template #4970. The Debian 10 Buster template is a prerequisite for creating Whonix ™ 15 templates.
  2. Non-Qubes-Whonix only since Qubes-Whonix ™ does not have a desktop environment installed - that is dependent on dom0.
  3. Users have the freedom to retain KDE applications and/or to reinstall those after the upgrade.
  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. 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.
  12. Due to issues with XFCE.
  13. VM XFCE is not being used in Qubes and package Whonix ™ XFCE Desktop Config is also not installed, so this step is unnecessary. If you want to apply this anyhow, it should be done in every AppVM.
  14. So it can be re-run.
  16. Because GUI application whonix-repository-wizard should not be run as root.
  17. To select the correct APT repository for use.
  19. 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

No user support in comments. See Support.

Comments will be deleted after some time. Specifically after comments have been addressed in form of wiki enhancements. See Wiki Comments Policy.

Anonymous user #1

15 days ago
Score 0 You
I cloned whonix-gw-14 & whonix-ws-14 to whonix-gw-15 & whonix-ws-15. After following the upgrade process, all appeared to go well. I changed sys-whonix from whonix-gw-14 to whonix-gw-15 and used torbrowser successfully. However, I can no longer get updates - err connecting.
Add your comment
Whonix welcomes all comments. If you do not want to be anonymous, register or log in. It is free.

Random News:

Please consider a recurring donation!

https | (forcing) onion

Share: Twitter | Facebook

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.

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

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

Whonix ™ is produced independently from the Tor® anonymity software and carries no guarantee from The Tor Project 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.