Getting Started


SecureDrop is a multi-machine design. To make development and testing easy, we provide a set of virtual environments, each tailored for a specific type of development task. We use Vagrant and VirtualBox to conveniently develop with a set of virtual environments, and our Ansible playbooks can provison these environments on either virtual machines or physical hardware.

To get started, you will need to install Vagrant, VirtualBox, and Ansible on your development workstation.



Tested on: Ubuntu 16.04 and Debian Stretch

sudo apt-get install -y build-essential dpkg-dev git linux-headers-$(uname -r) virtualbox

We recommend using the latest stable version of Vagrant, 1.8.5 at the time of this writing, which might be newer than what is in your distro’s package repositories. Older versions of Vagrant has been known to cause problems (GitHub #932, GitHub #1381). If apt-cache policy vagrant says your candidate version is not at least 1.8, you should download the current version from the Vagrant Downloads page and then install it.

# If your OS vagrant is recent enough
sudo apt-get install vagrant
# OR this, if you downloaded the deb package.
sudo dpkg -i vagrant.deb


We do not recommend installing vagrant-cachier. It destroys apt’s state unless the VMs are always shut down/rebooted with Vagrant, which conflicts with the tasks in the Ansible playbooks. The instructions in Vagrantfile that would enable vagrant-cachier are currently commented out.

VirtualBox should be at least version 5.x. See GitHub #1381 for documentation of incompatibility with the older VirtualBox 4.x release series.

Finally, install Ansible so it can be used with Vagrant to automatically provision VMs. We recommend installing Ansible from PyPi with pip to ensure you have the latest stable version.

sudo apt-get install python-pip

The version of Ansible recommended to provision SecureDrop VMs may not be the same as the version in your distro’s repos, or may at some point flux out of sync. For this reason, and also just as a good general development practice, we recommend using a Python virtual environment to install version 1.8.4 of Ansible. Using virtualenvwrapper:

sudo apt-get install virtualenvwrapper
mkvirtualenv -p python2.7 securedrop
pip install ansible==1.8.4

Mac OS X

Install the dependencies for the development environment:

  1. Vagrant
  2. VirtualBox
  3. Ansible.

There are several ways to install Ansible on a Mac. We recommend setting up a virtual environment to install Ansible since we are currently using Ansible 1.8.4:

pip install virtualenvwrapper
mkvirtualenv -p python2.7 securedrop
pip install ansible==1.8.4


If you install virtualenvwrapper and get a mkvirtualenv: command not found error, make sure source /usr/local/bin/ is in your ~/.bashrc.

Clone the repository

Once you’ve installed the prerequisites for the development environment, use git to clone the SecureDrop repo.

git clone

SecureDrop uses a branching model based on git-flow. The master branch always points to the latest stable release. Use this branch if you are interested in installing or auditing SecureDrop. Development for the upcoming release of SecureDrop takes place on develop, which is the default branch. If you want to contribute, you should branch from and submit pull requests to develop.