tor-browser-selenium

A Python library to automate Tor Browser with Selenium WebDriver.

📦 Installation

pip install tbselenium

Download geckodriver v0.31.0 from the geckodriver releases page and add it to PATH.

🚀 Usage

Download and extract Tor Browser, and pass its path when you initialize TorBrowserDriver. In the examples below, you should not pass "/path/to/tor-browser/" but the (Tor Browser) folder that contains the directory called Browser:

Using with system `tor`

tor needs to be installed (apt install tor) and running on port 9050.

from tbselenium.tbdriver import TorBrowserDriver
with TorBrowserDriver("/path/to/tor-browser/") as driver:
    driver.get('https://check.torproject.org')

Using with `Stem`

You can use Stem to start a new tor process programmatically, and connect to it from tor-browser-selenium. Make sure you have Stem installed: pip install stem:

import tbselenium.common as cm
from tbselenium.tbdriver import TorBrowserDriver
from tbselenium.utils import launch_tbb_tor_with_stem

tbb_dir = "/path/to/tor-browser/"
tor_process = launch_tbb_tor_with_stem(tbb_path=tbb_dir)
with TorBrowserDriver(tbb_dir, tor_cfg=cm.USE_STEM) as driver:
    driver.load_url("https://check.torproject.org")

tor_process.kill()

💡 Examples

Check the examples to discover different ways to use tor-browser-selenium

check_tpo.py: Visit the check.torproject.org website and print the network status message
headless.py: Headless visit and screenshot of check.torproject.org using PyVirtualDisplay
onion_service.py: Search using DuckDuckGo's Onion service
parallel.py: Visit `check.torproject.org`` with 3 browsers running in parallel
screenshot.py: Take a screenshot
stem_simple.py: Use Stem to start a tor process
stem_adv.py: Use Stem to launch tor with more advanced configuration

🛠️ Test and development

Browse the existing tests to find out about different ways you can use tor-browser-selenium.
For development and testing first install the necessary Python packages: pip install -r requirements-dev.txt
Install the xvfb package by running apt-get install xvfb or using your distro's package manager.
Run the following to launch the tests:

./run_tests.py /path/to/tor-browser/
By default, tests will be run using Xvfb, so the browser window will not be visible. You may disable Xvfb by setting the NO_XVFB environment variable:

export NO_XVFB=1

Running individual tests

First, export the path to Tor Browser folder in the TBB_PATH environment variable.

export TBB_PATH=/path/to/tbb/tor-browser/

Then, use py.test to launch the tests you want, e.g.:
py.test tbselenium/test/test_tbdriver.py
py.test tbselenium/test/test_tbdriver.py::TBDriverTest::test_should_load_check_tpo

Using a custom `geckodriver`

A custom geckodriver binary can be set via the executable_path argument:

TorBrowserDriver(executable_path="/path/to/geckodriver")

Disabling console logs

You can redirect the logs to /dev/null by passing the tbb_logfile_path initialization parameter:

TorBrowserDriver(..., tbb_logfile_path='/dev/null')

⚙️ Compatibility

Warning: Windows and macOS are not supported.

Tested with the following Tor Browser versions on Ubuntu:

Stable: 13.0.8
Alpha: 13.5a3

If you need to use a different version of Tor Browser, view the past test runs to find out the compatible selenium and geckodriver versions.

🔧 Troubleshooting

Solutions to potential issues:

Make sure you have compatible dependencies. While older or newer versions may work, they may cause issues.
- Tor Browser needs to be downloaded and extracted.
- Python selenium (pip install -U selenium).
- geckodriver version 0.31.0.
Running Firefox on the same system may help diagnose issues such as missing libraries and displays.
Process unexpectedly closed with status 1: If you encounter this on a remote machine you connect via SSH, you may need to enable the headless mode.
Port conflict with other (Tor) process: Pick a different SOCKS and controller port using the 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/error.
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.
WebGL is not supported in the headless mode started with headless=True due to a Firefox bug (#1375585). To enable WebGL in a headless setting, use pyvirtualdisplay following the headless.py example.

📚 Reference

Please use the following reference if you use tor-browser-selenium in your academic publications.

@misc{tor-browser-selenium,
  author = {Gunes Acar and Marc Juarez and individual contributors},
  title = {tor-browser-selenium - Tor Browser automation with Selenium},
  year = {2023},
  publisher = {GitHub},
  howpublished = {\url{https://github.com/webfp/tor-browser-selenium}}
}