Version 9 (modified by mikeperry, 7 years ago) (diff)


So You've Decided to Hack on the Tor Browser

Welcome to the Official Tor Browser Hacking Intro. This page is meant to give you an overview of how to get started with Tor Browser development. It covers building the browser, how we communicate and use trac to organize our issues and development process, what goes into the browser itself, and also provides links to other development resources and information.

The Bleeding Edge

The first thing you probably want to know is how to obtain the very latest (and sometimes greatest) Tor Browser builds, and how to build your own version of the Tor Browser from our source code. Well wait no further.

Nightly Builds

Currently, nightly builds are available courtesy of Linus Nordberg. They are available in the tbb-nightly-* subdirectories of his homedirectory on

As with all of our builds, it should be possible to reproduce byte-for-byte identical versions of all of those binaries from source. To learn how to do that, read on.

Building the Tor Browser

Our build system is based on Gitian, which was initially developed by the Bitcoin community. Gitian is a wrapper around Ubuntu's python-vm-builder and associated virtualization tools that helps to provide a clean, controlled, reproducible build environment in a fully automated fashion. We further wrap Gitian with our own helper scripts that download and authenticate inputs, and automate building and assembling each component piece of the browser into a final set of output packages for Linux, MacOS, and Windows.

This system enables us to provide secure, verifiable, byte-for-byte reproducible builds to ensure the integrity of our binaries and to protect the build process from compromise. We have written a pair of blog posts that describe in more detail why this is important, and the technical details behind how this is achieved, if you are curious.

To build the Tor Browser, you need an Ubuntu machine or VM. Once that is done, check out a copy of the builder repo with:

mkdir tor-browser-build
cd tor-browser-build
git clone
cd tor-browser-bundle/gitian

After that, you should be able to run 'make', 'make beta', 'make alpha', or 'make nightly' to build the entire bundle for all three platforms. The build scripts will detect any additional packages or configuration you need to perform on your system.

Inside that directory, you will also see a file with further information, should you run into any issues. In particular, the initial VM setup process is still somewhat fragile. In some cases your initial VM setup may fail or run into other issues, and you may need to restart your build with 'killall qemu-kvm'. See that README for more details on diagnosing and correcting these issues.

Reproducing an Existing Build

Every Tor Browser build includes a pair of files that describe exactly what versions of components went into making it, to allow easy reproducibility. These two files are located in the "Docs/sources" subdirectory of the Tor Browser destination directory.

To reproduce an existing bundle, inspect bundle.inputs and obtain the tor-browser-bundle.git commit hash describing the commit to build from.

Once you have this hash, you should be able to run something like the following commands:

   cp versions tor-browser-build/tor-browser-bundle/gitian/versions
   cd tor-browser-build/tor-browser-bundle/gitian
   git checkout 1929fd5db0802782066d52512d4c2a0fef144ed6

If your have a beta, alpha, or nightly build, you will need to place the versions file in the appropriate place (versions.beta, versions.alpha, or versions.nightly) and run the corresponding make target ('make beta', 'make alpha', or 'make nightly') instead of using just 'versions' and 'make' (which are for a stable series build).

Be aware that this process is not fully future-proof. In particular, if Ubuntu has updated their development tool chain since the bundles have been built, you may encounter differences between your resulting bundles and the original binaries. This should be rare, however, as we use only the "Long Term Support" versions of Ubuntu in our build VMs. The only reason they should change the toolchain is in the event of serious security issues in the development tools themselves.

Tor Browser Communication and Organizational Patterns

The Tor Browser development team is very geographically distributed. We use a few different written forms of communication to discuss development over the Internet: Mailing lists, IRC, and this bug tracker. We also hold weekly IRC meetings.

Communication Mechanisms and Meetings

The mailinglist for Tor Browser development discussion is tbb-dev. You can also subscribe to the list of Tor Browser code commits via tbb-commits. All updates to Tor Browser specific bugs are sent to tbb-bugs. Release tags and test builds are posted to tor-qa for community review and testing.

Our primary mode of day-to-day communication is the #tor-dev IRC channel on (port 6697 is ssl). We hold weekly meetings on this IRC channel at 18:00 UTC on Fridays. For details on our meeting format, please see the original meeting announcement post (note however that the time has changed since that posting).

How we use Trac

For historical reasons, Tor Browser tickets are spread across several Trac components: "Tor bundles/installation", "TorBrowserButton", "Firefox Patch Issues", and "Tor Launcher". We are considering consolidating many of these components and switching to keywords instead. For now, here are the keywords we use, along with their description.

Trac Keywords

What follows is a partial list of trac keywords we use to categorize issues.

Tickets that represent reported crash or hang issues
Tickets that represent usability issues
Tickets that represent frequently encountered support issues or blog/twitter commentary
Tickets that represent a violation of our identifier unlinkability design requirement.
Tickets that represent a violation of our fingerprinting unlinkability design requirement.
Tickets that represent a violation of our Disk Avoidance Security Requirement.
Tickets for problems with "New Identity" tbb-testcase Tickets for which we would like to have an automated testcase to prevent regressions.
Tickets in other Tor components that TBB needs solved.

In addition to this list, if you would like someone to review a patch, you should set the state of that ticket to "needs review" and tag it that that person's name, followed by the year, the month, and the letter 'R'. For example: MikePerry201311R.

Deep Hacking

Ok, so you've got the lay of the land now, and want to really dive in. Here's how everything is organized.

Core Components and Design

QA and Testing

Debugging the Tor Browser

Other Resources

Attachments (1)

Download all attachments as: .zip