Release Upgrade Whonix 16 to Whonix 17

From Whonix
Jump to navigation Jump to search

How to Release Upgrade from Whonix 16 to Whonix 17


Table: Release Upgrade Whonix Notices

Notice Description
Release Upgrade vs Re-Installation

To use Whonix 17, users can either:

Standard Updates
Automated Release Upgrade vs Manual Release Upgrade
  • Automated Release Upgrade is the newer method that has been implemented. It does not ask for user input and is therefore easier to use.
  • The former Manual Release Upgrade effectively did the same, but it offered more control over system customization. It is now deprecated. [1]
Configuration Files Resets Since this is an automated release upgrade, user modified configuration files (if any) in folder /etc will be reset, overwritten with the Debian or Whonix package version. The user is free to restore the configuration after the release upgrade.

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") update instructions.
  3. Consider running the optional sanity tests.
  4. Release Upgrade Whonix-Workstation (whonix-ws-16).
  5. Power off Whonix-Workstation (whonix-ws-16).
  6. Release Upgrade Whonix-Gateway (whonix-gw-16).
  7. Restart Whonix-Gateway (whonix-gw-16).
  8. Restart Whonix-Workstation (whonix-ws-16).

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 update

sudo apt full-upgrade

For testing purposes, install package nano.

sudo apt install nano ; echo $?

## ... successful installation of nano ... 0

Apt install fix missing.

sudo apt install -f

Expected upgrade.

Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.

Release Upgrade[edit]

  1. Backup all data - ideally have a clone of the VM(s) so it is possible to try again (if necessary).
  2. Perform the usual standard ("everyday") update instructions.
  3. Consider running the optional sanity tests.
  4. Run
  5. View release-upgrade command version. cat /usr/sbin/release-upgrade | grep version=
  6. Make sure the Kicksecure repository is enabled by re-running the derivative APT repository tool. [2]
  7. Check release-upgrade command version. Should be minimum 2.0, should show version="2.0".
  8. Consider keeping the full release upgrade log output. It will be required for Support in case there are issues.
  9. Perform the automated release upgrade using release-upgrade command. sudo release-upgrade
  10. Done. If everything went well, at the end it will show:

    INFO: OK. (release-upgrade version: 2.0) Release upgrade success.

  11. Reboot.
  12. Optional, recommended: Re-install Meta Packages and Safely Run Autoremove


  1. This method is still possible. All the automated script does is perform actions which the user could perform manually. If a manual release upgrade is desired, emulate what the release-upgrade script is doing. The manual release upgrading procedure is undocumented due to the size of the instructions and duplication involved.
    • This is required because the repositories have been split. Whonix is based on Kicksecure.
    • This step will not be required when upgrading from 17 to 18.

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 12 year success story and maybe DONATE!