Jump to: navigation, search

Upgrading Whonix 13 to Whonix 14

High Level Overview[edit]

1. Backup your data - ideally have a copy of the VM so it is possible to try again (if necessary).
2. Consider running the optional #Sanity Tests.
3. Upgrade Whonix-Workstation.
4. Power off Whonix-Workstation.
5. Upgrade Whonix-Gatway.
6. Restart Whonix-Gateway.
7. Restart Whonix-Workstation.

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


Both Non-Qubes-Whonix and Qubes-Whonix are supported.

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 (Konsole) 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.

First, upgrade the system's packages from Debian.


Backup the Tor config file.

Non-Qubes-Whonix users:

sudo cp /etc/tor/torrc ~/

Qubes-Whonix users:

When upgrading the TemplateVM, /etc/tor/torrc in the Whonix-Gateway TemplateBased ProxyVM (commonly called sys-whonix) will not be modified, because bind-dirs makes it persistent.

Update Whonix apt sources list.

sudo whonix_repository --enable --codename stretch

Update Debian apt sources list.

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

Qubes-Whonix only. Update Qubes apt sources list.

sudo sed -i "s/jessie/stretch/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

Upgrade torsocks and usability-misc first. [2] [3]

apt-get install torsocks usability-misc


apt-get-noninteractive dist-upgrade

Purge packages which are not required or deprecated in Whonix and have been replaced by new functionality. [4] anon-shared-kde-accessibility can be removed from the following command if accessibility tools are in use.

apt-get purge anon-shared-kde-accessibility iceweasel firefox-esr exim* unattended-upgrades cups control-port-filter-python packagekit at wpasupplicant apparmor-profile-sdwdate apparmor-profile-whonixcheck

Restart whonix-legacy service. [5]

service whonix-legacy restart

Update the package lists again. [6]

apt-get update

Non-Qubes-Whonix users please click on expand on the right.

apt-get install non-qubes-whonix-gateway

apt-get install non-qubes-whonix-workstation

Qubes-Whonix users please click on expand on the right.

apt-get install qubes-whonix-gateway

apt-get install qubes-whonix-workstation

apt-get install pulseaudio-qubes

Remove packages which are no longer required.

apt-get autoremove

Delete files which are no longer required. [7]

sudo rm /etc/apparmor.d/usr.lib.tor-controlport-filter

Remember to store the terminal (Konsole) log: File -> Save Output As

A poweroff is required.


  • Non-Qubes-Whonix users: All necessary steps are now complete.
  • Qubes-Whonix users: In Dom0

sudo qubesctl state.sls qvm.anon-whonix

Only complete the next step if all upgrades should be routed through sys-whonix. [8]

sudo qubesctl state.sls qvm.updates-via-whonix

The upgrade procedure is now complete.

Update Settings in Qubes R4[edit]

After successfully cloning whonix-gw to whonix-gw-14 and whonix-ws to whonix-ws-14, some users will want to configure a new sys-whonix-14 ProxyVM and have TemplateVMs use it for future updates. Follow these steps below.

1. Create a new Proxy-VM using the whonix-gw-14 template. Label the new VM "sys-whonix-14".
2. Edit the /etc/qubes-rpc/policy/qubes.UpdatesProxy file to set sys-whonix-14 as the target VM for the recently upgraded Whonix-Workstation and Whonix-Gateway. Copy and paste the text below.

whonix-ws $default allow,target=sys-whonix
whonix-ws $anyvm deny
whonix-gw $default allow,target=sys-whonix
whonix-gw $anyvm deny

whonix-ws-14 $default allow,target=sys-whonix-14
whonix-ws-14 $anyvm deny
whonix-gw-14 $default allow,target=sys-whonix-14
whonix-gw-14 $anyvm deny

## Note that policy parsing stops at the first match,
## so adding anything below "$anyvm $anyvm action" line will have no effect

## Please use a single # to start your custom comments

# Default rule for all TemplateVMs - direct the connection to sys-net
$type:TemplateVM $default allow,target=sys-net

$anyvm $anyvm deny

Save and exit.

3. After upgrading to Qubes-Whonix 14 in Qubes R4, the network setting for any Whonix TemplateVM should be set to none because a qrexec-based updates proxy is in use. [9]


  1. https://www.qubes-os.org/downloads/
  2. This avoids some torsocks warnings due to the torsocks upgrade.
  3. Provides apt-get-noninteractive.
  4. sysfsutils - https://github.com/Whonix/Whonix/commit/d7cb15aa96bd571368b54f8a980922d9e1982250
  5. A manual restart is required because apt-get-noninteractive is being used. This step is not crucial since it would also run after reboot.
  6. This is required because the Whonix repository URI has been upgraded to a new location by the whonix-legacy package.
  7. tor-controlport-filter was replaced by onion-grater. This deletion is of minor importance. (Only results in a useless apparmor profile.)
  8. https://github.com/QubesOS/qubes-mgmt-salt-dom0-virtual-machines/blob/master/qvm/updates-via-whonix.sls
  9. Qubes-Whonix 13 supports this feature as well after running apt-get dist-upgrade.

Random News:

Please contribute by helping to answer Whonix questions.

https | (forcing) onion

Share: Twitter | Facebook

This is a wiki. Want to improve this page? Help is welcome and volunteer contributions are happily considered! See Conditions for Contributions to Whonix, then Edit! IP addresses are scrubbed, but editing over Tor is recommended. Edits are held for moderation.

Whonix is a licensee of the Open Invention Network. Unless otherwise noted, the content of this page is copyrighted and licensed under the same Libre Software license as Whonix itself. (Why?)