6 Mar 2023 [CT] [guides]

CT-014: Whonix virtual machines on Debian using KVM

This is the 14th report in the Cypherpunk Transmission series.


Users that need advanced security and privacy can benefit from the principle of security by isolation by running Whonix1 virtual machines.

Whonix on the Qubes platform is probably the most extreme security setup, but it has relatively poor hardware support. This guide focuses on installing Whonix on a Debian host OS using the KVM2 (Kernel-based Virtual Machine) full virtualization solution.

Note: if at all possible, avoid using VirtualBox due to Oracle’s lack of transparency, known vulnerabilities, and licensing issues3.


0. Check virtualization support

Run lscpu | grep "Virtualization" to check if your hardware supports virtualization.

Hopefully, you should get one of the outputs below:

Virtualization: VT-x

Virtualization: AMD-V

1. KVM

1.1 Install

Open up a terminal on your host operating system, update the packages list, and install the required packages:

sudo apt update && sudo apt install --no-install-recommends qemu-kvm qemu-system-x86 libvirt-daemon-system libvirt-clients virt-manager gir1.2-spiceclientgtk-3.0 dnsmasq qemu-utils

1.2 Configure

Your regular user should be able to manage virtual machines without root. Add it to the libvirt and kvm groups:

sudo addgroup "$(whoami)" libvirt && sudo addgroup "$(whoami)" kvm

Reboot the machine with sudo reboot.

We can now enable and start KVM’s default networking:

sudo virsh -c qemu:///system net-autostart default && sudo virsh -c qemu:///system net-start default

2. Whonix

2.1 Download

Download the latest image file from the Whonix website (currently and the associated signature:

wget https://download.whonix.org/libvirt/ && wget https://download.whonix.org/libvirt/

Note: you can alternatively download from the onionsite with torsocks wget http://download.dds6qkxpwdeubwucdiaord2xgbbeyds25rbsgr73tbfpqpt4a6vjwsyd.onion/libvirt/ && torsocks wget http://download.dds6qkxpwdeubwucdiaord2xgbbeyds25rbsgr73tbfpqpt4a6vjwsyd.onion/libvirt/

2.2 Verify

To verify the image, we need the maintainer’s signing key:

wget https://www.whonix.org/keys/hulahoop.asc

Check the key’s fingerprint before importing it:

gpg --keyid-format long --import --import-options show-only --with-fingerprint hulahoop.asc

Only import the key if its fingerprint matches 04EF 2F66 6D36 C354 058B 9DD4 50C7 8B6F 9FF2 EC85:

gpg --import hulahoop.asc

Finally, we can start the cryptographic verification:

gpg --verify-options show-notations --verify Whonix*.libvirt.xz.asc Whonix*.libvirt.xz

You should see a gpg: Good signature from “HulaHoop” message.

Note: if you get a BAD signature output, restart from step 2.

2.3 Decompress

Decompress the .xz archive:

tar -xvf Whonix*.libvirt.xz

2.4 License Agreement

Read and agree to the Whonix ToS/license:



2.5 Import VM Templates

Add the virtual networks:

sudo virsh -c qemu:///system net-define Whonix_external*.xml && sudo virsh -c qemu:///system net-define Whonix_internal*.xml

Note: if the virtual bridge “virbrX” already exists, edit the Whonix_external*.xml and Whonix_internal*.xml files and change the name to something new (ie. virbr3).

Activate them:

sudo virsh -c qemu:///system net-autostart Whonix-External && sudo virsh -c qemu:///system net-start Whonix-External

sudo virsh -c qemu:///system net-autostart Whonix-Internal && sudo virsh -c qemu:///system net-start Whonix-Internal

Import the Gateway and Workstation images:

sudo virsh -c qemu:///system define Whonix-Gateway*.xml && sudo virsh -c qemu:///system define Whonix-Workstation*.xml

2.6 Copy Image Files

sudo cp --sparse=always Whonix-Gateway*.qcow2 /var/lib/libvirt/images/Whonix-Gateway.qcow2

sudo cp --sparse=always Whonix-Workstation*.qcow2 /var/lib/libvirt/images/Whonix-Workstation.qcow2

2.7 (optional) Cleanup

Remove archive files and temporary folders:

rm Whonix* && rm -r WHONIX*

2.8 (optional) Increase memory

Note: Whonix-Gateway virtual machine needs to be given at least 1 GB of RAM to be able to start the Xfce desktop environment.

Before starting the machines, we can increase the maximum memory with:

virsh setmaxmem <vm_name> <memsize> --config

Set the actual memory:

virsh setmem <vm_name> <memsize> --config

Restart the VM:

virsh -c qemu:///system start <vm_name>

Note: replace <vm_name> with the virtual machine’s name and <memsize> with the desired memory size; vCPU and memory allocation can also be set from the Virtual Machine Manager GUI.

2.9 Start Whonix

We first need to start Whonix-Gateway and then the Workstation-Workstation.

2.9.1 CLI

Start the Gateway:

sudo virsh start Whonix-Gateway

And the Workstation:

sudo virsh start Whonix-Workstation

2.9.2 GUI

Alternatively, start the Virtual Machine Manager from Start Menu > Applications > System > Virtual Machine Manager.

Start the Gateway and Workstation by clicking on Whonix-Gateway > Open > Play and then Whonix-Workstation > Open > Play.

3. Post install

Finalize the installation by running sudo setup-dist in a Whonix-Gateway terminal.

Next, change the default changeme password for user in both Whonix-Gateway and Whonix-Workstation:

sudo passwd user

Use upgrade-nonroot to keep your systems up-to-date.


That’s it, you can now use Whonix on Debian with KVM.


Let me know if you find this helpful and, depending on interest, I will do my best to post a new Cypherpunk Transmission report every (other?) Monday.

Questions, edits and suggestions are always appreciated @ /about/.


Credit goes to gnuteardrops from monero.graphics for the amazing xkcd graphic. Work and xkcd Script font licensed under CC BY-NC 3.0.