Git repository and branches

You will need to clone the Tails Git repository, and to checkout the branch that you want to build (most likely, not master): learn more about our Git branches layout.

Using Vagrant

Tails can be built easily in a virtual machine using Rake, Vagrant and VirtualBox. The process requires a minimum of 1 GB of free memory and a maximum of 10 GB of free storage.

Installing the dependencies in Debian

If you run Debian Jessie

Install the needed tools:

sudo apt-get install git virtualbox rake ruby-childprocess \
     ruby-erubis ruby-i18n ruby-log4r ruby-net-scp ruby bsdtar curl

If you run Debian Wheezy

  1. Add Debian Jessie and wheezy-backports to your APT sources:

    echo "deb jessie main" | \
        sudo tee /etc/apt/sources.list.d/jessie.list
    echo "deb wheezy-backports main" | \
        sudo tee /etc/apt/sources.list.d/wheezy-backports.list
  2. Pin all packages from Debian Jessie and unstable at 500 (apt_preferences(5)):

    sudo tee /etc/apt/preferences.d/jessie <<EOF
    Package: *
    Pin: release o=Debian,a=jessie
    Pin-Priority: 500
  3. Install the needed tools:

    sudo apt-get install git virtualbox rake ruby-childprocess/jessie \
        ruby-net-scp/jessie ruby-erubis ruby-i18n ruby-log4r bsdtar curl \

In both Debian Wheezy and Jessie

At the moment Tails relies on a version of Vagrant (the 1.4.x series) that is not packaged in Debian any more. Here's a workaround for both Debian Wheezy and Jessie:

sudo tee /etc/apt/preferences.d/tails-build-vagrant <<EOF
Package: vagrant
Pin: version 1.4.3+dfsg1-3
Pin-Priority: 550

Package: ruby-net-ssh
Pin: version 1:2.6.8-2
Pin-Priority: 550
echo "deb unstable main" | \
    sudo tee /etc/apt/sources.list.d/20141010T042049Z.list
sudo apt-get -o Acquire::Check-Valid-Until=false update
sudo apt-get install vagrant ruby-net-ssh
sudo rm /etc/apt/sources.list.d/20141010T042049Z.list
sudo apt-get update

If you run Virtualbox >4.3 (5.0 is in Jessie backports at the moment) you will have to patch Vagrant a bit:

--- /usr/share/vagrant/plugins/providers/virtualbox/driver/meta.rb.orig 2016-02-12 11:58:06.150337645 +0100
+++ /usr/share/vagrant/plugins/providers/virtualbox/driver/meta.rb      2016-02-12 11:58:38.778726368 +0100
@@ -45,7 +45,8 @@
             "4.0" => Version_4_0,
             "4.1" => Version_4_1,
             "4.2" => Version_4_2,
-            "4.3" => Version_4_3
+            "4.3" => Version_4_3,
+            "5.0" => Version_4_3

           if @version.start_with?("4.2.14")

Building Tails using Vagrant

Once all dependencies are installed, get the Tails sources and checkout the development branch:

git clone
cd tails
git checkout devel

Build Tails using Vagrant:

rake build

The first time, this can take a little while to download the base virtual machine from Tails mirror (around 300 MB). It will then boot the machine, set it up and start the build process. When done, several tails-* files should appear in the current directory.

After you are done working on Tails, do not forget to shut the virtual machine down:

rake vm:halt

One may also want to customize their image before building.

To know all available Rake tasks, please run rake -T.

Local HTTP proxy

If you have a local HTTP proxy, the build system will use it as long as you properly set the http_proxy environment variable. The easiest way to do so is to run:

export http_proxy=http://proxy.lan:3142

This needs to be done before any other operations.

Build options

Options regarding the build process can be set using the TAILS_BUILD_OPTIONS environment variable. Muliple options must be separated by whitespaces.

The following options are available:

Memory build settings

Tails builds way faster when everything is done in memory. If your computer runs Linux and happens to have more than 7 GB of free memory before you start the virtual machine, it will automatically switch to 'build in RAM' mode.

To force a specific behaviour please set:

  • ram: start the virtual machine with 7 GB of memory, build Tails inside a tmpfs. Build fails if the system is not in a proper state to do so.
  • noram: start the virtual machine with 512 MB of memory if not already done, build Tails using the virtual machine hard disk.

HTTP proxy settings

Building Tails requires downloading a little bit more than 1 GB of Debian packages. To preserve bandwidth and developer sanity, using a HTTP proxy is nearly a must. Tails virtual machine contains a fully configured local HTTP proxy that will be used if no other local proxy is defined.

The following flags can be used to force a specific behaviour:

  • extproxy: use the proxy configured through the http_proxy environment variable. Fail if it is not set.
  • vmproxy: use the local proxy configured in the virtual machine even if a local HTTP proxy is set.
  • noproxy: do not use any HTTP proxy.

SquashFS compression settings

One of the most expensive operations when building Tails is the creation of the final SquashFS. It also depends on the compression algorithm used. When working on the stable or testing branch, the image will be made using the slow but efficient default. Any other setup will switch to the faster gzip.

Forcing a specific behaviour can be done using:

  • gzipcomp: always use gzip to create the SquashFS.
  • defaultcomp: always use the default compression algorithm.

Clean-up settings

Some operations are preserved accross builds. Currently they are:

  • The wiki (for documentation).

In case you want to delete all these, the following option is available:

  • cleanall: force a clean up before starting the build.

Virtual CPUs settings

The number of virtual CPUs that are allocated in the virtual machine can be set through:

  • cpus=n: allocate n CPUs to the virtual machine.

Obviously you should not allocate more virtual CPUs than the number of cores available to the host system. When using Linux, the number of CPUs allocated will default to be the same as the host system.

Git settings

The build system can only work on files that have been commited to the Git repository. By default, it will refuse to start a build in presence of uncommited changes. This behaviour can be controlled by:

  • ignorechanges: allow to make a build that will ignore changes in the Git repository.


The fastest build you could pretend to get can be done by setting:

export TAILS_BUILD_OPTIONS="ram cache extproxy gzipcomp"

This will force the build to happen in RAM and allow skipping the boostrap stage if one is cached, and will use use an HTTP proxy external to the virtual machine, and SquashFS compression will be done using gzip.

Building manually

In order to build Tails manually, you need a running Debian Jessie system and some backports. Anything else will fail.


The following Debian packages need to be installed:

  • our live-build 2.x package, adapted for Wheezy and later. Its version is something like 3.0.5+really+is+2.0.12-0.tails2. One can install it from:

    deb builder-jessie main

    This APT repository's signing key can be found:

    It is certified by the Tails signing key, and its fingerprint is:

    221F 9A3C 6FA3 E09E 182E  060B C798 8EA7 A358 D82E

    You should pin that repository, so that live-build isn't upgraded to the version of jessie.

    Package: *
    Pin: release o=Debian,a=stable
    Pin-Priority: 700
    Package: *
    Pin: origin
    Pin-Priority: 800

    Then install these dependencies from Jessie:

    apt-get install \
      dpkg-dev \
      eatmydata \
      gettext \
      intltool \
      libyaml-libyaml-perl \
      libyaml-perl \
      libyaml-syck-perl \
      perlmagick \
      po4a \
      syslinux-utils \
      time \

    And install these dependencies from jessie-backports (please verify manually that the following command actually does install the expected versions):

    apt-get install \
      debootstrap/jessie-backports \

Configure live-build

Remove any line matching /^[[:space:]]*LB.*MIRROR.*=/ in /etc/live/build.conf.

Build process

Every build command must be run as root, at the root of a clone of the tails repository.

In short, a build shall be done using:

lb clean --all && lb config && lb build

Running lb config or lb build in an environment that wasn't full cleaned first is not supported.

Customize the build process if needed

If you need to set custom build settings that are specific to your local environment, such as a custom Debian mirror or APT proxy, you probably want to configure live-build a bit.

The most common customizations are documented on this wiki:

More documentation about this can be found in the Debian Live Manual.

More information

More documentation about the build process can be found in the Debian Live Manual.

Related pages