Welcome to The Complete Guide to Qubes & Whonix, in the following sections you will learn how to set up a secure & virtualized desktop environment. While reading this guide please keep the following legend in mind to maximize your learning proficiency. Text that is red is considered IMPORTANT and should always be understood, text that is blue is optional reading that provides additional information on a section.

What is Qubes?

Qubes is a free and open-source operating system focused on a single-user computing experience, leveraging xen-based virtualization to allow for the creation and management of isolated compartments called Qubes.

These Qubes (virtual machines) have a predefined set of one or many isolated applications for personal or professional projects or managing
the network stack/firewall. Full and complete or majorly stripped down operating systems can run inside of most Qubes. Different levels of trust for each Qube can be determined and set based upon it’s needs.

Qubes uses a template system to easily install the most used privacy qubes. You can create these templates as a disposable or persistent environment depending on your operational needs. More can be learned at qubes-os{dot}org/intro.

What is Whonix?

Whonix might just be the most trusted and watertight privacy operating system pair in the world. Whonix uses 2 virtualized operating systems working together to hide your identity and maintain your privacy by routing all traffic through the Tor Network.

Whonix is not a VPN, VPNs are much easier and faster than Tor, however they are not nearly as anonymous. VPN administrators can log both where a user is connecting from and
their connection destination. Even if a VPN provider claims they don’t log… they do. Whonix is split into two seperate operating systems:

  • The Gateway OS – routes all traffic through Tor, acts as a firewall
  • The Workstation OS – run applications securely, connects to the gateway

Whonix is now bundled with Qubes to make our lives easier.


  • At least 8GB of ram (16GB recommended)
  • A CPU that supports virtualization (VT-x with EPT or AMD-V with RVI or Intel VT-d or AMD-Vi[AMD IOMMU])
  • 32GB Free Storage Space
  • 8GB+ USB Drive

Installing Qubes

Download and Burn the Installation Media

  • Go to qubes-os{dot}org and download the latest available ISO
  • Burn the ISO to a USB
  • Boot up the installation USB on your computer of choice

Go through the Qubes Installation

  • It is highly recommended to follow DoD data destruction standards before installing Qubes to a storage device
  • Upon boot, select Test Media and Install Qubes OS X.X.X
  • Select your language and keyboard layout
  • Under system, select the Installation Destination and leave it on auto configuration unless you require specific partioning.
  • Select I would like to make additional space then Encrypt My Data
  • When you click Done on this section, you will be prompted to create a Disk Encryption password. It is recommended to make this as long as possible while still retaining memory of it!
  • Save the Disk Encryption Password
  • Select Delete All and then Reclaim Space (delete’s existing partitions)
  • You will be redirected to the main menu where you can proceed to Date & Time and select your timezone.
  • Leave the root accound disabled.
  • Now create your user with a strong password differing from your encryption password.
  • Once back at the main installation screen, select Begin Installation
  • Wait for Qubes OS to install
  • Once installation is complete, select Reboot System

Go through the Qubes Configuration

  • Enter Qubes with Hypervisor Enabled
  • Decrypt your Disk
  • Select Qubes OS
  • Select your desired Qube templates to install (Fedora 36, Debian 11, and/or Whonix)
  • Enable Use sys-net qube for both networking and USB devices
  • Enable System and template updates over the Tor anonimity network using Whonix
  • Select Done and click Finish Configuration
  • Wait for default templates to install. (Do not be alarmed if the installation freezes, it’s still working, please be patient)

Get familiar with your Qubes desktop environment

  • Log into your user account
  • The Qube Manager Tray is the blue isometric cube
    icon in the top-right corner of your desktop. You can manage/view your
    currently running qubes and their resource usage.
  • In the Qube Manager, you may create, delete, and manage all your qubes.
  • The System Menu is located in the top-left corner of your desktop. Here, you can launch various tools as well as isolated application qubes.
  • Your Qubes Devices are located in the top-right
    corner of your desktop. Here you can view all your connected devices and
    provide passthrough to specific qubes (USB passthrough is blocked by default).
  • The Network Manager is located in the top-right corner of your desktop. Here you can connect to various wifi and ethernet access points.

Setup Network Devices

  • Open Qube Manager from the blue isometric cube icon in the top-right corner of your desktop.
  • Select sys-net and shutdown the qube
  • Once shut down, open the sys-net qube settings
  • Go to the devices tab and locate your USB controllers (keep this window open until you click ok)
  • Move each desired USB controller to the right panel to enable them (This is only recommended if you absolutely need access to USB devices such as storage controllers and network adapters)
  • Click Apply! If your
    laptop has internal USB peripherals (not PS2) such as a keybaord,
    modifying these options may disable it and could break your installation
    if you restart. Remove each USB passthrough one at a time and restart
    the sys-net qube until your interal peripheral works again.
  • Click OK to close the USB passthrough window
  • Start the sys-net qube and wait for initialization
  • You should now have access to your external network adapter
  • Connect to the internet

Update your Qubes OS

  • In the top-left System Menu, open the Terminal Emulator
  • Run the following update command

Qubes R4.0 and before:

sudo qubes-dom0-update

Qubes R4.1 and later:

sudo qubes-dom0-update --show-output --console
  • This command may fail at first, a Connection Wizard popup may appear to configure your internet connection for Whonix.
  • Rerun the update command above and wait for the systems to update. (These updates are routed through the Tor Network and may take a long time to complete)
  • Once the update verifies packages, you will need to enter Y when prompted, the default is NO and if you press enter, you will need to restart the update process.

Installing Recommended Software in the Whonix Template

  • Open the System Menu and hover over Template: whonix-ws-XX (IMPORTANT) and open the XFCE terminal.
  • Update the Whonix system template
sudo apt-get update && sudo apt-get upgrade -y

Install Kleopatra to use PGP encryption.

sudo apt-get install kleopatra
  • Close the XFCE terminal.

Installing VeraCrypt (requires a debian-11 qube)

  • Open the System Menu and hover over Template: debian-11 (IMPORTANT) and open the terminal.
  • Update the system template
sudo apt-get update && sudo apt-get upgrade -y
  • Install VeraCrypt to use PGP encryption.
  • Get the VERACRYPT_DOWNLOAD_LINK from www{dot}veracrypt{dot}fr
  • Choose the Debian 11 package and copy the download link into the wget command. (Always verify PGP signatures before installing!)
  • Install the .DEB package
sudo dpkg -i vc.deb
  • Any installation errors should be fixed with
sudo apt-get --fix-broken install
sudo dpkg -i vc.deb

Enabling Recommended Software in the Whonix Qube

  • Open Qube Manager and select the whonix-ws-XX template.
  • Open Settings > Applications and move KeePassXC and Kleopatra to the right panel.
  • Click Apply and OK.
  • Shutdown the anon-whonix qube in the Qube Manager.
  • Open Settings > Applications and move KeePassXC and Kleopatra to the right panel.
  • Click Apply and OK.

Installing I2P

Installing I2P on Whonix

  • Open the System Menu and hover over Template: whonix-ws-XX (IMPORTANT) and open the XFCE terminal.

Add the I2P signing key to your Whonix template

scurl-download --proxy --tlsv1.2

Then display the key’s fingerprint and verify

gpg --keyid-format long --import --import-options show-only --with-fingerprint i2p-archive-keyring.gpg

The finger print should look something like (verify the fingerprint via the whonix wiki about I2P)

7840 E761 0F28 B904 7535 49D7 67EC E560 5BCF 1346

After confirming the signing key matches, copy the signing key to your APT keyring folder

sudo cp i2p-archive-keyring.gpg /usr/share/keyrings/i2p-archive-keyring.gpg

Now add the I2P APT repository

echo "deb [signed-by=/usr/share/keyrings/i2p-archive-keyring.gpg] tor+ bullseye main" | sudo tee /etc/apt/sources.list.d/i2p.list

Install both I2P packages

sudo apt update && sudo apt full-upgrade
sudo apt install --no-install-recommends i2p i2p-keyring

Configure the I2P service to start automatically upon boot (Leave defaults and answer ‘Yes’)

sudo dpkg-reconfigure i2p

Edit the local worker connection address (to avoid Whonix Tor Proxy)

sudoedit /var/lib/i2p/i2p-config/clients.config.d/00-net.i2p.router.web.RouterConsoleRunner-clients.config

Change to


  • Follow the instructions at /post/3294a9a91bef5f76cec1 to enable I2P service inside of the TemplateVM to generate /var config files OR
  • To make the above config persist, make a startup script:
sudo nano /
  • Add the following bash script:
sed -i 's/' /var/lib/i2p/i2p-config/clients.config.d/00-net.i2p.router.web.RouterConsoleRunner-clients.config
systemctl restart i2p
  • Make the script executable
sudo chmod +x /
  • (make sure this file is in the root of your whonix template)
  • When you start your anon-whonix qube, always open Xfce Terminal and type
sudo /
  • You can make this a default startup option but it might not work.
  • Continue the following:

Enable I2P on anon-whonix startup

sudo systemctl enable i2p
  • Shutdown the whonix-ws-XX template.
  • Start / restart the anon-whonix qube
  • Open the System Menu and hover over anon-whonix (IMPORTANT) and open the XFCE terminal.
  • Start I2P service is not enabled
sudo systemctl start i2p

Now that I2P is installed on your whonix qube, you must configure Tor Browser to allow I2P connections.

Navigate to `about:config` in Tor Browser.

Search for and change the following settings

  • Search for `extensions.torbutton.use_nontor_proxy` set it to `true`
  • Search for `network.proxy.http` set it to ``
  • Search for `network.proxy.http_port` set it to `4444`
  • Search for `network.proxy.no_proxies_on` set it to ``
  • Search for `network.proxy.socks_remote_dns` set it to `false`
  • Search for `` set it to `false`
  • Search for `` set it to `false`
  • Search for `javascript.enabled` set it to `false`

When following these instructions, the
about:config changes in Tor Browser worsen the browser fingerprint. This
is unavoidable if the user intends to use I2P. The modified Tor Browser
should only be used for I2P purposes.

Note: when configuring anon-whonix‘s Tor Browser for I2P, you will not be able to browse the Tor Network when I2P proxy settings are enabled.

Navigate to your I2P Router Console at `` to check statistics. You will most likely need to wait 20 or more minutes before you can access any eepsites through a proxy (first run only). As you
build more tunnels, you will get a faster and more reliable connection.

If errors appear like: `Network: ERR-UDP Disabled and Inbound TCP host/port not set` or `ERR-Clock Skew of X min` or `WARN [Timestamper]
.router.time.RouterTimestamper: Unable to reach any of the NTP servers …`, they can be safely ignored.

Once the Local Tunnels (shared clients) section shows a green connection, I2P should be fully functional and it is possible to browse eepsites.. Some users report this process can be lengthy and can take more than 10 minutes before the tunnels are stable/available.

I2P is functional over Tor but users should be aware that I2P developers do not support it nor recommend it to be used over Tor. Just because it is functional does not mean it is
supported. In other words, I2P upstream developers will not change any I2P behaviours just for the sake of connectivity issues of I2P over Tor because I2P is not designed to be running over Tor in the first place. However this is used to mask your ip from the I2P network.


Congratulations, you now have a general understanding of Whonix on Qubes and how to run it securely! It is highly recommended that you reread this guide to fully understand everything you have learned. It is your responsibility to stay up to date with technologies as they change to ensure your safety and security. Good luck and stay safe!

Steve Dark

By Steve Dark

Steve Dark is a seasoned cybersecurity professional with over 10 years of experience in the field. He holds a Bachelor's degree in Computer Science from Stanford University and a Master's degree in Cybersecurity from MIT. Steve is known for his meticulous attention to detail and his ability to identify even the most subtle security vulnerabilities. When he's not researching protocols or playing in HackTheBox, Steve enjoys sipping on his favorite tea blend while munching on his favorite cookies. Despite his serious profession, Steve has a playful side and loves engaging in friendly hacking competitions with colleagues and peers