How-to: Install the Stable Version of Qubes-Whonix ™ 16

From Whonix
Jump to navigation Jump to search


Installation Instructions, Release Notices, Disposable Template Setup, Updates over Tor



Table: Qubes-Whonix ™ 16 Release Notices

Notice Description
Qubes Version Support

Novice or intermediate users can generally ignore footnotes (like 1) unless experiencing difficulties or having questions. See also introduction chapter Whonix ™ Footnotes and References.

Qubes R4.1 Known Issues
Other Issues

In case technical issues are experienced such as broken dom0, broken qubes-dom0-update are Qubes issues and unspecific to Whonix ™ and should therefore be either reported to, or added as a comment to an existing issue there (if appropriate). This is further elaborated in What to post in this Qubes-Whonix forum and what

The instructions on this wiki page have bad usability. These are mostly out of control of the Whonix ™ project. See footnote for more information. [1]

Qubes-Whonix ™ 15 to Qubes-Whonix ™ 16 Release Upgrade This is a notice for users who currently have Qubes-Whonix ™ 15 installed.

If Qubes-Whonix ™ 15 is installed and you want to get Qubes-Whonix ™ 16, there is no need to uninstall Qubes-Whonix ™ 15 before proceeding according to the instructions on this wiki page. This is because the new templates (whonix-ws-16, whonix-gw-16) will be installed alongside the old templates (whonix-ws-15, whonix-gw-15).

In this case, App Qubes that were previously configured to use Qubes-Whonix ™ 15 templates will keep using them -- the Templates of any App Qubes are not automatically changed to the newly installed Qubes-Whonix ™ 16 templates. This is a Qubes default and unspecific to Qubes-Whonix ™. [2] Therefore, a manual change must be applied to App Qubes settings by the user. The rationale is to prevent unexpected changes of an App Qube's Template without the user's consent. [3]

After the Qubes-Whonix ™ installation has finished, it is recommended to manually change the setting of any App Qubes still using Qubes-Whonix ™ 15 Templates to the Qubes-Whonix ™ 16 Templates. [4]

A wholly different, alternative option is to ignore all the advice on this wiki page and instead perform a Release Upgrade according to the Release Upgrade Whonix ™ 15 to Whonix ™ 16 instructions.

Preexisting Qubes-Whonix ™ 16 Installations

This is a notice for users who already have Qubes-Whonix ™ 16 installed.

If any user data was stored in Qubes-Whonix ™ VMs, before re-installation, back up any existing data.

If you are already running Qubes-Whonix ™ 16, it must be uninstalled before a complete re-installation is performed. This is also necessary when Qubes-Whonix ™ 16 is bundled as part of future Qubes releases, and auto-configuration is selected during the installation.

Choose re-installation options A) OR B). (listed in order of preference)


Update dom0[edit]

Launch a dom0 terminal.
Click the Qubes App Launcher (blue/grey "Q")Open the Terminal Emulator (Xfce Terminal)


Upgrade Qubes dom0. This step is mandatory. [5]

  • Qubes R4.0: sudo qubes-dom0-update
  • Qubes R4.1 [6]: sudo qubes-dom0-update --show-output --console

Verify whonix_version is 16.

If the previous sudo qubes-dom0-update was completed, it should not be necessary to verify the version number. However, this is mentioned because many users fail to update dom0 packages beforehand.

In dom0. View contents of file /srv/formulas/base/virtual-machines-formula/qvm/whonix.jinja.

sudo cat /srv/formulas/base/virtual-machines-formula/qvm/whonix.jinja

Example output:

{% set whonix_version = salt['pillar.get']('qvm:whonix:version', '16') %} {% set whonix_repo = salt['pillar.get']('qvm:whonix:repo', '[omitted for brevity]') %}

If it shows something else, then Qubes dom0 is outdated. In that case, it is not possible to continue. [7] [8]

Download Whonix ™ Templates and Configure sys-whonix and anon-whonix[edit]

Info Note: This downloading procedure can take a long time to finish. Fast Internet connections take only a few minutes, while slow connections can take twenty minutes or more (it is far slower over Tor).

Download both Whonix-Gateway ™ and Whonix-Workstation ™ Templates.

In dom0, run. [9]

To download Whonix-Gateway ™ and Whonix-Workstation ™ run this command:

qvm-template --enablerepo=qubes-templates-community install whonix-gw-16 whonix-ws-16

Configure sys-whonix and anon-whonix safely. [10]

In dom0, run. [11]

sudo qubesctl state.sls qvm.anon-whonix

Refer to the footnotes for troubleshooting tips. [12]

Optional Steps[edit]

Whonix ™ Disposable Template[edit]

In Qubes R4 and above a whonix-ws-16-dvm Disposable Template can optionally be set up as a base for Disposables. [13]

In dom0, run.

sudo qubesctl state.sls qvm.whonix-ws-dvm

There is a Qubes bug that may cause the Disposable Template to run instead of the Unspecific to Whonix ™. If this happens, just log off and back on. There is no need to reinstall or set up anything.

Updates over Tor[edit]


To force all Template updates over Tor, use qubesctl in dom0. [14]

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

To undo this setting, modify /etc/qubes-rpc/policy/qubes.UpdatesProxy in dom0. [15] See also How-to: Fix dom0 Qubes-Whonix ™ UpdatesProxy Settings.


To force dom0 updates over Tor, set Qubes' dom0 UpdateVM to sys-whonix. [16]

  • Qube ManagerSystemGlobal SettingsDom0 UpdateVM: sys-whonixOK

To revert this change, set Qubes' dom0 UpdateVM to sys-firewall or another preferred VM. [17]

  • Qubes ManagerSystemGlobal SettingsDom0 UpdateVM: sys-firewallOK

Enable AppArmor[edit]

AppArmor is enabled by default. No extra steps required.

Update and Launch Applications[edit]

Before starting applications in the Whonix-Workstation ™ App Qube, update both Whonix-Gateway ™ and Whonix-Workstation ™ Templates.

To launch an application like Tor Browser:

  • Qubes App Launcher (blue/grey "Q")Domain: anon-whonixTor Browser (AnonDist)

Additional Information[edit]


Whonix first time users warning Warning:

  • If you do not know what metadata or a man-in-the-middle attack is.
  • If you think nobody can eavesdrop on your communications because you are using Tor.
  • If you have no idea how Whonix ™ works.

Then read the Design and Goals, Whonix ™ and Tor Limitations and Tips on Remaining Anonymous pages to decide whether Whonix ™ is the right tool for you based on its limitations.

It is recommended to refer to these additional references:


Novice or intermediate users can generally ignore footnotes (like 1) unless experiencing difficulties or having questions. See also introduction chapter Whonix ™ Footnotes and References.

  1. This is also true for other distribution Templates. For example, users of the Qubes debian-10 Template will not have all their App Qubes updated to the new debian-11 Template by default when it is downloaded.
  2. For example, this could result in breakage if custom-installed applications in the old Template were not available in the new Template.
  3. Upgrade Qubes dom0 is required to make sure: Older, similar references:
  4. Using --show-output --console is optional, recommended because of Qubes upstream bug: qubes-dom0-update shows No updates available in case of network is down / qubes-dom0-update fails to notice if repositories are unreachable / network is
  5. Testers-only: It should not be necessary to manually update that file because the Qubes dom0 stable package should have updated it already. If it didn't, then the cause is general issues unspecific to Whonix ™.

    1. In dom0 open file whonix.jinja with root rights.

    sudo nano /srv/formulas/base/virtual-machines-formula/qvm/whonix.jinja

    2. Change 15 to 16.

    3. Save the file.

  6. The following Qubes issues are for developers understanding, reference only:
  7. The following qubes-dom0-update command is:
    • Optional.
    • Useful because it has a progress indicator while the subsequent qubesctl command does not. (Qubes feature request: add salt download progress It very confusing to have a long running download command with progress bar, specifically over Tor.
    • Insufficient by itself - the subsequent qubesctl command that follow is mandatory as per phase out manual use of qubes-dom0-update by user / replace it by and Dev/Qubes#salt.
    • --enablerepo=qubes-templates-community:
      • --enablerepo=qubes-templates-community can be omitted if Qubes Community Templates Repository is already enabled in dom0.
      • Qubes Community Templates Repository should already be enabled as per Qubes default unless disabled by user, restored Qubes-Whonix ™ from backup or some other edge case.
      • Recommending to type --enablerepo=qubes-templates-community is bad usability since users cannot copy from their VM browser where they are most likely reading this to dom0. But too many people reported this issue. had to enable Qubes templates community
      • If Qubes Community Templates Repository is not enabled in dom0, explicitly add --enablerepo=qubes-templates-community or enable through editing dom0 file /etc/yum.repos.d/qubes-templates.repo.

    In dom0.

    1. Open file /etc/yum.repos.d/qubes-templates.repo in a text editor with root rights.

    sudo nano /etc/yum.repos.d/qubes-templates.repo

    2. In section [qubes-templates-community], add the following.

    enabled = 1

    3. Save.

    4. Done.

    Qubes Community Templates Repository has been enabled. Command line parameter --enablerepo=qubes-templates-community should be no longer required.

    5. Report.

    Please report if step this was necessary for you!

  8. No progress indicator is shown. Qubes feature request: add salt download progress
  9. If qubesctl still does not work, try shutting down Qubes OS and rebooting the machine. Please report if this step was necessary for you!
  10. For developers only, link to related source code file:
  11. How to change Template update method from Whonix to just another appvm?
  12. Or manually set the torified UpdateVM in dom0 terminal. qubes-prefs updatevm sys-whonix
  13. To revert this change in dom0 terminal, run. qubes-prefs updatevm sys-firewall

We believe security software like Whonix needs to remain open source and independent. Would you help sustain and grow the project? Learn more about our 10 year success story and maybe DONATE!