A Python library to automate Tor Browser with Selenium WebDriver.
Warning
Windows and macOS are currently not supported.
pip install tbselenium
Download geckodriver
v0.31.0 from the geckodriver releases page and add it to PATH.
Download and extract Tor Browser, and pass its folder's 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
:
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')
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()
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
-
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 runningapt-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 disableXvfb
by setting theNO_XVFB
environment variable:export NO_XVFB=1
- 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
A custom geckodriver
binary can be set via the executable_path
argument:
TorBrowserDriver(executable_path="/path/to/geckodriver")
You can redirect the logs to /dev/null
by passing the tbb_logfile_path
initialization parameter:
TorBrowserDriver(..., tbb_logfile_path='/dev/null')
Warning: Windows and macOS are not supported.
Tested with the following Tor Browser versions on Ubuntu:
- Stable: 14.0
- Alpha: 14.0a9
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.
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 thesocks_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, usepyvirtualdisplay
following the headless.py example.
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}}
}
We greatly benefited from the tor-browser-bundle-testsuite and tor-browser-selenium projects.