Tor Browser automation with Selenium.
Python Shell
Switch branches/tags
Clone or download

tor-browser-selenium Build Status

A Python library to automate Tor Browser with Selenium.


pip install tbselenium

You also need to install geckodriver v0.17.0 from the geckodriver releases page. Make sure you install the v0.17.0 version; newer or older versions will not be compatible with the current Tor Browser series.

Test your geckodriver installation by running the command below; it must return geckodriver 0.17.0:

geckodriver --version

Basic usage

from tbselenium.tbdriver import TorBrowserDriver
with TorBrowserDriver("/path/to/TorBrowserBundle/") as driver:

TorBrowserDriver does not download Tor Browser Bundle (TBB) for you. You should download and extract TBB and provide its path when you initialize TorBrowserDriver.

Test and development

Install the Python packages that are needed for development and testing:

pip install -r requirements-dev.txt

Install xvfb package by running apt-get install xvfb or using your distro's package manager.

Run the following to launch the tests:

./ /path/to/TorBrowserBundle/

By default, tests will be run using Xvfb, so the browser will not be visible. You may disable Xvfb by exporting the following environment variable:

export NO_XVFB=1

Running individual tests

First, export a TBB_PATH environment variable that points to the TBB version you want to use:

export TBB_PATH=/path/to/tbb/tor-browser_en-US/

Then, use py.test to launch the tests you want, e.g.:

  • py.test tbselenium/test/
  • py.test tbselenium/test/


Check the examples to discover different ways to use TorBrowserDriver


Tested with the following Tor Browser Bundle versions on Debian and Ubuntu:

  • 7.5.4
  • 8.0a7
  • 6.5.1

Windows and macOS are not supported.


Solutions to potential issues:

  • Outdated (or incompatible) Python selenium package: This is the source of various obscure errors. Make sure you have selenium version 3.3 or above.
  • Outdated Tor Browser Bundle: Download and use a more recent TBB version.
  • Try an older geckodriver version that matches the current Firefox version number inside the Tor Browser Bundle.
  • Port conflict with other (Tor) process: Pick a different SOCKS and controller port using socks_port argument.
  • Use tbb_logfile_path argument of TorBrowserDriver to debug obscure errors. This can help with problems due to missing display, missing libraries (e.g. when the LD_LIBRARY_PATH is not set correctly) or other errors that Tor Browser logs to standard output.
  • When you use LAUNCH_NEW_TBB_TOR option and get the following error message during the initialization, it's likely that Tor failed to bootstrap (due to network etc.):
Can't load the profile. Profile Dir: /tmp/tmpO7i1lL/webdriver-py-profilecopy If you specified a log_file in the FirefoxBinary constructor, check it for details
  • driver.get_cookies() returns an empty list. This is due to Private Browsing Mode (PBM), which Selenium uses under the hood. See #79 for a possible solution.


We greatly benefited from the following two projects: