{"id":13521845,"url":"https://github.com/webfp/tor-browser-selenium","last_synced_at":"2025-05-14T15:11:41.124Z","repository":{"id":32777125,"uuid":"36368865","full_name":"webfp/tor-browser-selenium","owner":"webfp","description":"Tor Browser automation with Selenium.","archived":false,"fork":false,"pushed_at":"2025-04-01T11:51:21.000Z","size":452,"stargazers_count":571,"open_issues_count":7,"forks_count":101,"subscribers_count":23,"default_branch":"main","last_synced_at":"2025-04-12T01:52:31.197Z","etag":null,"topics":["automation","selenium","stem","tor","tor-browser"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/webfp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-05-27T13:33:49.000Z","updated_at":"2025-04-08T17:51:36.000Z","dependencies_parsed_at":"2024-02-13T20:28:02.193Z","dependency_job_id":"02fed811-f50f-4f4f-a89a-2f5e7af7f812","html_url":"https://github.com/webfp/tor-browser-selenium","commit_stats":{"total_commits":409,"total_committers":15,"mean_commits":"27.266666666666666","dds":0.6552567237163814,"last_synced_commit":"83b352c23fcdd672ef07714f92a0b0b68a8c29f8"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webfp%2Ftor-browser-selenium","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webfp%2Ftor-browser-selenium/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webfp%2Ftor-browser-selenium/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webfp%2Ftor-browser-selenium/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/webfp","download_url":"https://codeload.github.com/webfp/tor-browser-selenium/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248505873,"owners_count":21115354,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","selenium","stem","tor","tor-browser"],"created_at":"2024-08-01T06:00:38.593Z","updated_at":"2025-04-12T01:52:36.600Z","avatar_url":"https://github.com/webfp.png","language":"Python","funding_links":[],"categories":["Python","Applications"],"sub_categories":["Other applications"],"readme":"# tor-browser-selenium [![Build Status](https://app.travis-ci.com/webfp/tor-browser-selenium.svg?branch=main)](https://app.travis-ci.com/webfp/tor-browser-selenium)\n\n\nA Python library to automate Tor Browser with Selenium WebDriver.\n\n## 📦 Installation\n\n\u003e [!WARNING]\n\u003e Windows and macOS are currently not supported.\n\n```\npip install tbselenium\n```\n\nDownload `geckodriver` v0.31.0 from the [geckodriver releases page](https://github.com/mozilla/geckodriver/releases/) and add it to PATH.\n\n## 🚀 Usage\n\nDownload and extract [Tor Browser](https://www.torproject.org/projects/torbrowser.html.en), 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`:\n\n\n### Using with system `tor`\n\n`tor` needs to be installed (`apt install tor`) and running on port 9050.\n\n```python\nfrom tbselenium.tbdriver import TorBrowserDriver\nwith TorBrowserDriver(\"/path/to/tor-browser/\") as driver:\n    driver.get('https://check.torproject.org')\n```\n\n### Using with `Stem`\nYou 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`:\n\n\n```python\nimport tbselenium.common as cm\nfrom tbselenium.tbdriver import TorBrowserDriver\nfrom tbselenium.utils import launch_tbb_tor_with_stem\n\ntbb_dir = \"/path/to/tor-browser/\"\ntor_process = launch_tbb_tor_with_stem(tbb_path=tbb_dir)\nwith TorBrowserDriver(tbb_dir, tor_cfg=cm.USE_STEM) as driver:\n    driver.load_url(\"https://check.torproject.org\")\n\ntor_process.kill()\n```\n\n\n## 💡 Examples\nCheck the [examples](https://github.com/webfp/tor-browser-selenium/tree/master/examples) to discover different ways to use `tor-browser-selenium`\n* [check_tpo.py](https://github.com/webfp/tor-browser-selenium/tree/master/examples/check_tpo.py): Visit the `check.torproject.org` website and print the network status message\n* [headless.py](https://github.com/webfp/tor-browser-selenium/tree/master/examples/headless.py): Headless visit and screenshot of check.torproject.org using [PyVirtualDisplay](https://pypi.org/project/PyVirtualDisplay/)\n* [onion_service.py](https://github.com/webfp/tor-browser-selenium/blob/main/examples/onion_service.py): Search using DuckDuckGo's Onion service\n* [parallel.py](https://github.com/webfp/tor-browser-selenium/tree/master/examples/parallel.py): Visit `check.torproject.org`` with 3 browsers running in parallel\n* [screenshot.py](https://github.com/webfp/tor-browser-selenium/tree/master/examples/screenshot.py): Take a screenshot\n* [stem_simple.py](https://github.com/webfp/tor-browser-selenium/tree/master/examples/stem_simple.py): Use Stem to start a `tor` process\n* [stem_adv.py](https://github.com/webfp/tor-browser-selenium/tree/master/examples/stem_adv.py): Use Stem to launch `tor` with more advanced configuration\n\n\n\n## 🛠️ Test and development\n\n* Browse the [existing tests](https://github.com/webfp/tor-browser-selenium/tree/main/tbselenium/test) to find out about different ways you can use `tor-browser-selenium`.\n\n* For development and testing first install the necessary Python packages:\n  `pip install -r requirements-dev.txt`\n\n* Install the `xvfb` package by running `apt-get install xvfb` or using your distro's package manager.\n\n* Run the following to launch the tests:\n\n  `./run_tests.py /path/to/tor-browser/`\n\n* By default, tests will be run using `Xvfb`, so the browser window will not be visible.\nYou may disable `Xvfb` by setting the `NO_XVFB` environment variable:\n\n  `export NO_XVFB=1`\n\n\n### Running individual tests\n* First, export the path to Tor Browser folder in the `TBB_PATH` environment variable.\n\n`export TBB_PATH=/path/to/tbb/tor-browser/`\n\n* Then, use `py.test` to launch the tests you want, e.g.:\n\n* `py.test tbselenium/test/test_tbdriver.py`\n* `py.test tbselenium/test/test_tbdriver.py::TBDriverTest::test_should_load_check_tpo`\n\n\n### Using a custom `geckodriver`\nA custom `geckodriver` binary can be set via the `executable_path` argument:\n\n```python\nTorBrowserDriver(executable_path=\"/path/to/geckodriver\")\n```\n\n### Disabling console logs\nYou can redirect the logs to `/dev/null` by passing the `tbb_logfile_path` initialization parameter:\n```python\nTorBrowserDriver(..., tbb_logfile_path='/dev/null')\n```\n\n## ⚙️ Compatibility\n\nWarning: **Windows and macOS are not supported.**\n\n[Tested](https://travis-ci.org/webfp/tor-browser-selenium) with the following Tor Browser versions on Ubuntu:\n\n* **Stable**: 14.0.9\n* **Alpha**: 14.5a5\n\nIf you need to use a different version of Tor Browser, [view the past test runs](https://travis-ci.org/webfp/tor-browser-selenium) to find out the compatible `selenium` and `geckodriver` versions.\n\n## 🔧 Troubleshooting\n\nSolutions to potential issues:\n\n* Make sure you have compatible dependencies. While older or newer versions may work, they may cause issues.\n  - [Tor Browser](https://www.torproject.org/download/) needs to be downloaded and extracted.\n  - Python [`selenium`](https://www.selenium.dev/) (`pip install -U selenium`).\n  - `geckodriver` [version 0.31.0](https://github.com/mozilla/geckodriver/releases/tag/v0.31.0).\n\n* Running Firefox on the same system may help diagnose issues such as missing libraries and displays.\n* `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](https://github.com/webfp/tor-browser-selenium/blob/master/examples/headless.py).\n* Port conflict with other (`Tor`) process: Pick a different SOCKS and controller port using the `socks_port` argument.\n* 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.\n* `driver.get_cookies()` returns an empty list. This is due to Private Browsing Mode (PBM), which Selenium uses under the hood. See [#79](https://github.com/webfp/tor-browser-selenium/issues/79) for a possible solution.\n* WebGL is not supported in the headless mode started with `headless=True` due to a Firefox bug ([#1375585](https://bugzilla.mozilla.org/show_bug.cgi?id=1375585)). To enable WebGL in a headless setting, use `pyvirtualdisplay` following the [headless.py](https://github.com/webfp/tor-browser-selenium/tree/master/examples/headless.py) example.\n\n## 📚 Reference\nPlease use the following reference if you use `tor-browser-selenium` in your academic publications.\n\n```\n@misc{tor-browser-selenium,\n  author = {Gunes Acar and Marc Juarez and individual contributors},\n  title = {tor-browser-selenium - Tor Browser automation with Selenium},\n  year = {2023},\n  publisher = {GitHub},\n  howpublished = {\\url{https://github.com/webfp/tor-browser-selenium}}\n}\n```\n\n## 🙌 Credits\nWe greatly benefited from the [tor-browser-bundle-testsuite](https://gitlab.torproject.org/tpo/applications/tor-browser-bundle-testsuite) and [tor-browser-selenium](https://github.com/isislovecruft/tor-browser-selenium) projects.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebfp%2Ftor-browser-selenium","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebfp%2Ftor-browser-selenium","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebfp%2Ftor-browser-selenium/lists"}