Jump to: navigation, search

Dev/Build Documentation/7

Build Documentation[edit]


This page documents how to build Whonix VirtualBox images. If you have any questions or need help, get in Contact.

It documents how to build the stable version of Whonix. Rather, if you are interested in building the testers-only version of Whonix, click Build Documentation.

Knowledge assumed: basic principles of Virtualization; operation of your platform; Linux knowledge: how to install Debian and basic command line knowledge.

Only one prerequisite: you need a working internet connection.

For discussion related to the development and build process of Whonix images get in contact.

How to use the resulting images, is documented in the Documentation.


  • Short: Better build in a virtual machine!
    Long:/dev/mapper/loop0p1 (and /dev/nbd0) (used for mounting the images) is hard coded inside Whonix build scripts. Beware if you are using such devices. It may conflict with TrueCrypt. (And possibly other tools relying on /dev/mapper/loop0p1 (and /dev/nbd0).) To avoid damage to your host system, it may be wise to build Whonix inside a Virtual Machine.
  • Short: Don't add private files to Whonix's source code folder!
    Long: Technically, it would work. Everything in whonix_gateway folder will get installed on Whonix-Gateway, whonix_workstation folder respectively, whonix_shared folder goes to both Whonix machines. This is recommended against. Those files would get managed by either the whonix-gateway-files, whonix-workstation-files or the whonix-shared-files package. When you later update Whonix debian packages, your files would get deleted by the package manager. Also adding private files to Whonix's source code folder, later contributing to Whonix's development and accidentally pushing the wrong git branch would be a disaster. Better add your private files to Whonix after building Whonix. Or add a custom build step adding your files, which then get copied from a folder outside of Whonix's source folder.
  • Short: Gnome user? Please disable device auto mounter. You can do this by running the following command. (If you don't know if you are a Gnome user or not, just run this command, it won't hurt.) Long: [1]
gsettings set org.gnome.desktop.media-handling automount-open false
  • Short: Make sure there aren't any VMs in VirtualBox already called Whonix-Gateway or Whonix-Workstation!
    Long: [2]
  • Short: Check if the OpenPGP public keys are still up to date. If you are in luck, you never have to update the keys yourself and the Whonix maintainer will keep them updated.
    Long: For better security.
  • Short: Do not try to build Whonix-Gateway and Whonix-Workstation at the same time!
    Long: Building Whonix-Gateway and Whonix-Workstation at the same time is not supported due to limitations in the build script. In other words, do not try to run sudo ~/Whonix/whonix_build --build --tor-gateway and sudo ~/Whonix/whonix_build --build --tor-workstation at the same time. The build would probably fail.

Build Anonymity[edit]

While downloading the required tools for building Whonix your internet service provider could if he want notice that you want to build Whonix. This is especially interesting, if you want to redistribute Whonix, but still want to stay anonymous. The full story can be read in the chapter Build Anonymity.

Build Security[edit]

Especially, but not exclusively, if you want to distribute Whonix images, you should improve the security of your build environment.

  • Build on a dedicated build system, install security updates... (Security Guide)
  • All installation medium[3] and all downloaded/used code must be verified (including all software on the host).
  • Hashes, fingerprints in the scripts and the wiki is not to be trusted. Verify everything.
  • Read Trust.

Host Preparation[edit]

  • You need to build on Debian Testing (Jessie). (How to obtain Debian safely: [4]) [5]
  • Build dependencies and configurations get automatically applied, so you don't have to worry about that. [6]
  • It is recommended to set your terminal (for example Konsole) to unlimited scrollback, so you can watch the full build log.

Building Whonix in Whonix[edit]

You only have to read this, if you want to build Whonix in Whonix.
If you are interested, click on Expand on the right.

Building Whonix in Whonix is possible as well (if the Whonix version you are using as host is also based on Debian Testing (Jessie)). Unfortunately, apt-cacher-ng does not like Whonix's apt repository on sourceforge.net. Adrelanos already reported a bug. As long as this bug isn't fixed, you need to disable Whonix's apt repository while building Whonix. You can do this using the whonix_repository tool.

sudo whonix_repository --disable

Introduction into Whonix Source Code[edit]

If you prefer to read and understand the source code just by reading scripts you may skip this optional chapter.

When you like to mess with the source code, it would probably help a lot if you at least know what .img, .vdi, .vmdk and .ova are being used for. See Source Code Introduction.

Preparation Steps[edit]

Only required if you want to redistribute (official) Whonix builds.

See Redistribution Pre Building.

Get the Signing Key[edit]

This chapter is recommended for better security, but not strictly required. (See Trust)

Download the key.

curl --tlsv1 --proto =https -o patrick.asc https://www.whonix.org/patrick.asc

Check fingerprints/owners without importing anything.

gpg --with-fingerprint patrick.asc

Verify it shows the following.

pub  4096R/2EEACCDA 2014-01-16 Patrick Schleizer <adrelanos@riseup.net>
      Key fingerprint = 916B 8D99 C38E AF5E 8ADC  7A2A 8D66 066A 2EEA CCDA
sub  4096R/CE998547 2014-01-16 [expires: 2016-10-05]
sub  4096R/119B3FD6 2014-01-16 [expires: 2016-10-05]
sub  4096R/77BB3C48 2014-01-16 [expires: 2016-10-05]

If it checks out, import the key.

gpg --import patrick.asc

Only getting the signing key from one source, from the download you want to verify isn't safe. For better security, Learn about Whonix Signing Key.

Get the Source Code[edit]

Install git and curl

sudo apt-get install git curl

Get source code including git submodules.

git clone --recursive https://github.com/Whonix/Whonix

Remember it's Whonix, not whonix! If you are prompted for a username for github, it means you have mistyped the web address.

Get into the source folder.

cd Whonix

(For experimental, faster, alternative method, see footnote. [7])

OpenPGP Verify the Source Code[edit]

This chapter is recommended for better security, but not strictly required.[8]

Get a list of available git tags.

git tag

Verify the tag you want to build.

## ... Replace with tag you want to build.
git verify-tag

Output should look similar to this.

object 1844108109a5f2f8bddcf2257b9f3675be5cfb22
type commit
tagger Patrick Schleizer <adrelanos@riseup.net> 1392320095 +0000

gpg: Signature made Thu 13 Feb 2014 07:34:55 PM UTC using RSA key ID 77BB3C48
gpg: Good signature from "Patrick Schleizer <adrelanos@riseup.net>" [ultimate]

The warning.

gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.

Is explained on the Whonix Signing Key page and can be ignored.

By convention, git tags should point to signed git commits. [10] (forum discussion) It is recommended to verify the signature of the git commit as well. (Replace with the actual git tag you want to verify.)

git verify-commit^{commit}

Output should look similar to this.

commit 5aa1c307c943be60e7d2bfa5727fa5ada3a79c4a
gpg: Signature made Sun 07 Dec 2014 01:22:22 AM UTC using RSA key ID 77BB3C48
gpg: Good signature from "Patrick Schleizer <adrelanos@riseup.net>" [ultimate]
Author: Patrick Schleizer <adrelanos@riseup.net>
Date:   Sun Dec 7 01:22:22 2014 +0000


Choose Version[edit]

Git checkout, which version (or git branch) you want to build.

In case you want to build a specific git tag.

git checkout

You have to replace with the actual version you want to build. The stable version, the testers-only version or the developers version. Common sense is required while choosing the right version number. For example, the biggest version number is not necessarily the most recommended / latest stable version. You can learn about current versions reading Whonix News Blogs. New versions are also announced on the whonix-devel mailing list. So you could alternatively check its archives. Signing up for whonix-devel is another way to get informed about new releases.

Clean up and Sanitize[edit]

This is also important for security.

Get a list of eventually extraneous files and folders. [11]

git clean -ndff

And look if that looks sane. (Generally should, unless you are modifying Whonix's source code, then you should understand git a bit better and know what you are doing.) If it looks like the following, everything is fine.

Would remove packages/apparmor-profile-gwenview/
Would remove packages/kde-privacy/

Now get rid of these folders.

git clean -dff

Should show.

Removing packages/apparmor-profile-gwenview/
Removing packages/kde-privacy/

Make sure you have checked out the right commit for each git submodule.

git submodule update --init --recursive

Check if there are no extraneous files. This is important for security.

git status

Should only show and nothing else.

# Not currently on any branch.
nothing to commit (working directory clean)

Otherwise we'd need to get rid of these files first.

Build Configuration (Optional)[edit]

Introduction (Optional)[edit]


Usually you do not have to change the build configuration. Whonix build from source code comes with safe defaults. Whonix's APT Repository will NOT be used.

The most interesting build configurations (Terminal-Only, NoDefaultApps etc.) are documented in the following chapters below.

If you are interested, click on Expand on the right.

If you used build configurations earlier, it might be better to delete your build configuration folder since a few example files names change changed in meanwhile.

sudo rm -r /etc/whonix_buildconfig.d

Alternatively, if you know what you are doing, you can of course also manually get into the /etc/whonix_buildconfig.d folder, examine and change its contents to your linking.

/etc/whonix_buildconfig.d is a modular flexible .d style configuration folder.

Less popular build configurations are documented in the buildconfig.d folder and on the Dev/Source_Code_Intro#Build_Configuration page in a less user friendly documented way.

It is recommended to copy and paste text when creating build configuration files to avoid typos. Also keep care, that your editor even when you are using copy and paste, won't capitalizes variable names which are supposed to be lower case.

Terminal-Only Builds (Optional)[edit]


Advanced users can build a no-default-gui / no-KDE / terminal-only Whonix-Gateway and/or Whonix-Workstation.

If you are interested, click on Expand on the right.

terminal-only builds are less tested due to lack of contributor manpower. Should work well in principle.

--gui none

NoDefaultApps Builds (Optional)[edit]


Advanced users can install fewer recommended packages to make the resulting build smaller and more customizable. (recommended as in useful to have, not necessary to have them for some other reason.)

If you are interested, click on Expand on the right.

NoDefaultApps builds are less tested due to lack of contributor manpower. Should work well in principle.

NOTE: You most likely want to combine this with terminal-only builds, see above.

NOTE: Such a NoDefaultApps system would for example not include Arm on Whonix-Gateway. So please do not create a NoDefaultApps build and then complain, that packages are missing.

To learn, what packages for example the whonix-gateway-packages-recommended package would install, search in the debian/control file for Package: whonix-gateway-packages-recommended.

We're just excluding a few meta packages. (Meta packages are packages, which do not hold files on its own, but only instruct apt-get to install other packages.)

--apps false

CurrentSources Builds (Optional)[edit]


Advanced users could install from Current Sources (custom) instead of from Frozen Sources (default in 7.4.0 and above). Both options have security advantages and disadvantages.

If you are interested, click on Expand on the right.

CurrentSources builds are rarely tested due to lack of contributor manpower. Should work reasonably well in principle as long as no packages are removed from Debian. The worst thing that can probably happen, is that the build fails due to missing packages.

Frozen Sources:

  • Whonix's build script will use http://snapshot.debian.org instead of the more popular ftp.us.debian.org.
  • Snapshot.debian.org will never change, i.e. their packages and versions will remain the same forever*[currentsources 1] [currentsources 2].
  • Using Frozen Sources has the advantage that all builders end up with a very similar [currentsources 3] image. This gives builders more confidence, that they have ended up with an intact image.
  • Are a precondition for the Verifiable Builds security feature.
  • It follows, when building a fresh image it will contain outdated packages. (You can upgrade after booting for the first time.)
  • Package downloads are still verified, but we have to ignore the valid-until field. Which means, a man-in-the-middle attack capable adversary could feed you with packages even older than configured in the version of Whonix you are building. Any packages which were ever signed with the APT repository signing key of that codename[currentsources 4]. You might not like that and therefore prefer building from Current Sources.
  • At some point, for example if remotely exploitable vulnerabilities are found in the apt-get version (defined by Frozen Sources) it may be dangerous to continue building that version.
  • We should compare our images with each other to ensure no man-in-the-middle attack has happened while building Whonix.

Current Debian APT repository:

  • Packages and versions may change over time. Packages may be removed, replaced with others, versions get security other other updates.
  • Build script may break the older the Whonix source code version release becomes. (Break as in the build won't finish - not as in creating images containing bugs.)
  • Each builder ends up with an individual image.
  • Valid-until field gets verified.

If you prefer to build from Current Sources, please add the following build script command line argument.

--freshness current


  1. Besides a few rare exceptions.
  2. As long the great snapshot.debian.org service lasts.
  3. Timestamps, temporary files and who knows what else (open research question) differ.
  4. Codename as in Testing, Wheezy, Jessie.

64bit Builds (Optional)[edit]


Advanced users can create 64bit instead of 32bit builds.

If you are interested, click on Expand on the right.

64bit builds are less tested due to lack of developer manpower. Should work well in principle.

Note, you cannot build 64 bit if you are running a 32 bit kernel. [12] In that case, try installing the packages linux-image-amd64 and linux-headers-amd64. Then boot that amd64 kernel by choosing it in your boot menu. (This does not require re-installation of the whole system. Just make sure you boot with an amd64 kernel.)

By default, Linux 32 bit is used and linux-image-686-pae linux-headers-686-pae linux-image-486 linux-headers-486 kernel is installed. The 486 kernel only gets installed for compatibility reasons. If you have modern hardware, you can omit it. Or if you have ancient hardware, you could ommit the 686 kernel. This can be changed using any of the following command line parameters.

Linux 64 bit. Less tested. Only installs linux-image-amd64 linux-headers-amd64 kernel. [13]

--arch amd64

Linux 32 bit. Only installs linux-image-686-pae linux-headers-686-pae kernel. Does not install linux-image-486 linux-headers-486 kernel.

--arch i386

Linux 32 bit. Only installs linux-image-486 linux-headers-486 kernel. Does not install linux-image-686-pae linux-headers-686-pae kernel.

--kernel linux-image-amd64 --headers linux-headers-amd64

You could also combine --arch with --kernel and --headers.

kFreeBSD. entirely untested and most likely needs work. Lacks --kernel and --headers.

kFreeBSD 64 bit.

--arch kfreebsd-i386

kFreeBSD 32 bit.

--arch kfreebsd-amd64

Whonix for arm64 development discussion:

Whonix APT Repository (Optional)[edit]


Whonix's APT Repository is disabled by default since Whonix 7.3.3. You may enjoy this for Trust reasons. You can later update Whonix debian packages from source code if you want. If you are interested in enabling Whonix's APT repository right after building (you could do that also after booting your build for the first time if you wanted) for convenience while sacrificing the extra security of not updating from source code, click on Expand on the right side.

Do you want to opt-in for Whonix's APT Repository?


(See build script --help.)

Only Minimal Report (Optional)[edit]


By opt-in Whonix's last build step creates a report file of all hdd contents. (See Verifiable Builds for details.) This step is optional. First introduced in Whonix 7.4.8. Whonix should work fine without that step. It is used for extra security. This step takes quite some time. If you want to enable it, click on Expand on the right side.

Do you want to opt-in of the report creation build step?

--report true

APT Cache (Optional)[edit]


When building in a virtual machine, builders can use their own http proxy (apt cache) on the host, which will greatly improve build speed when building several times in a row (debugging, development).

If you are interested, click on Expand on the right.

This isn't required when you are building virtual machine images, because then apt-cacher-ng is automatically set up for you. Only useful when using --install-to-root in a virtual machine.

Requires Whonix or above.


On the host.

sudo apt-get install apt-cacher-ng

Be sure to have a firewall, so not the whole internet can use your apt-cacher-ng service.

Inside your Virtual Machine.

Don't forget to replace with your host's internal IP (use "sudo ifconfig" on your host to find out what your internal IP is).

export http_proxy=

Don't forget to add -E to sudo, so environment variables are preserved. Examples.

sudo -E ./whonix_build --install-to-root --tor-gateway --build
sudo -E ./build-steps.d/1100_prepare-build-machine --install-to-root --tor-gateway

Custom Build Tags[edit]

Only if you are using your own git tags! In that case click on Expand on the right.

If you created for example a git tag "9.1" and want to receive Whonix News for "9", apply this.

Please look into packages/whonixcheck/etc/whonix.d/30_whonixcheck_default. Look for.

## Override what version whonixcheck will show in its window title and which
## Whonix News will be downloaded. Change only if you know what you are doing.

Create a file /etc/whonix.d/50_whonixcheck_user and add for example. (You still have to replace "7" with the custom git tag you are using.


When you later update from Whonix debian packages from for example "9.1" to "10", these settings have to be commented out.

VM Settings (Optional)[edit]


Only relevant for VM builds.

Examples below. Values can be changed.

VirtualBox's --vmsize option (virtual RAM).

--vmram 128

VirtualBox's --vram option (virtual video RAM).

--vram 12

grml-debootstrap's --vmsize option.

--vmsize 200G

grml-debootstrap's --filesystem option.

--file-system ext4

grml-debootstrap's --hostname option. (The anon-base-files package will change that later again.)

--hostname host

grml-debootstrap's --password option.

--os-password changeme

grml-debootstrap's --debopt option.

--debopt "--verbose"

Skip Steps (Optional)[edit]


--sanity-tests false

Source Code Changes[edit]

Only in case you made changes to the Whonix source folder! In that case click on Expand on the right.
Not required if you only added using your own build configuration in /etc/whonix_buildconfig.d folder.

If you made changes to the Whonix source code, it is the easiest to use the following build parameter.

--allow-uncommitted true

Or if you are not building from a git tag, it is the easiest to use the following build parameter.

--allow-untagged true

Otherwise changes would have to be committed to git first and then a git tag would have to be created.

VM Creation[edit]

Build a Whonix-Gateway virtual machine image.

sudo ~/Whonix/whonix_build --build --tor-gateway

Eventually, if you wish to use a different build configuration for Whonix-Workstation, change the contents in your /etc/whonix_buildconfig.d folder.

Build a Whonix-Workstation virtual machine image.

sudo ~/Whonix/whonix_build --build --tor-workstation

The resulting .ova images can be found in ~/whonix_binary folder.

Check if all went ok.

Please report back any issues!

If you want to build for the second time, made changes or want to build a newer version, you have to reset debian/changelog [14] and remove (or rename) any eventually already existing Whonix-Gateway and/or Whonix-Workstation in VirtualBox. Open a terminal (such as Konsole).

Reset debian/changelog.

git checkout -- debian/changelog

Delete eventually already existing Whonix-Gateway virtual machine. Warning: This will delete a virtual machine named Whonix-Gateway from Virtual Box!

sudo ~/Whonix/whonix_build --clean --tor-gateway

Delete eventually already existing Whonix-Workstation virtual machine. Warning: This will delete a virtual machine named Whonix-Workstation from Virtual Box!

sudo ~/Whonix/whonix_build --clean --tor-workstation

From now, you have two options. If you do not wish to use different build configurations for Whonix-Gateway and Whonix-Workstation (for example, if you do not wish to create a terminal-only Whonix-Gateway and a full Whonix-Workstation), you could use the sudo ~/Whonix/whonix_build_both wrapper script to build both virtual machines at once. If you wish to use different build configurations, you must use the whonix_build script to build one after the other as described above.



Remove temporary files.

Warning, this will run git clean -d --force --force in Whonix's main source code folder (~/Whonix) as well as in all sub folders of the Whonix packages folder ~/Whonix/packages. This means, if you knowingly added any files to any of these folders that have not been committed to git, these will be deleted.




OPTIONAL (Only in case something goes wrong or if you want to audit or develop Whonix.)

See Debugging.

Final Steps[edit]

Only required if you want to redistribute (official) Whonix builds.

See Redistribution Post Building.

Source Code / Hacking / Development Tickets[edit]

See Developer Portal.

Contact / About adrelanos[edit]

For general inquiries, see Contact.

To learn about adrelanos, the person who maintains Whonix, its OpenPGP key, see adrelanos.mediawiki.


  1. Otherwise a file manager may be opened while building Whonix which could lead to issues.
  2. Because the build script would fail, because it tries to create VMs either named Whonix-Gateway or Whonix-Workstation.
  3. Such as DVD or USB.
  4. Debian ISO OpenPGP verification
  5. The build scripts could be adapted to run on other *NIX systems as well but currently they assume apt-get and grml-debootstrap to be available. You need about 15 GB of free space.
  6. By build-steps.d/1100_prepare-build-machine.))
  7. Get source code. Get into the source folder. Speedy parallel fetching of git submodules.
    (Credits: Thanks to Karmazzin for his answer on sourceforge.)
    git clone https://github.com/Whonix/Whonix && cd Whonix && cat .gitmodules | grep -Po '".*"' | sed 's/.\(.\+\).$/\1/' | while sleep 0.1 && read line; do git submodule update --init "$line" & done
  8. See Trust.
  9. Defined as per TUF: Attacks and Weaknesses:
  10. Beginning from git tag 9.6 and above.
  11. There currently is a small issue. (A limitation of git.)
  12. https://github.com/grml/grml-debootstrap/pull/13
  13. For --arch amd64, the following is implicitly added unless you manually set these.
    --kernel linux-image-amd64 --headers linux-headers-amd64
  14. Otherwise the .deb packages would not get rebuild.
  15. https://github.com/Whonix/Whonix/blob/master/help-steps/cleanup-files

Random News:

Join us testing new AppArmor profiles for improved security! (forum discussion)

Impressum | Datenschutz | Haftungsausschluss

https | (forcing) onion
Share: Twitter | Facebook | Google+
This is a wiki. Want to improve this page? Help welcome, 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 (g+) is a licensee of the Open Invention Network. Unless otherwise noted above, content of this page is copyrighted and licensed under the same Free (as in speech) license as Whonix itself.