# tor-relay-scanner: finding a Tor relay your network can actually reach > tor-relay-scanner is a small Python script that pulls the full list of Tor relay addresses from onionoo, probes random ones for reachability, and hands the ones that answer to Tor Browser as bridges or writes them into a torrc file. It suits a user in a censored country whose Tor client cannot reach the built-in relays, and it is not a tool for anything beyond that. **ValdikSS/tor-relay-scanner** — Tor Relay availability checker, for using it as a bridge in countries with censorship - Repository: https://github.com/ValdikSS/tor-relay-scanner - Stars: 621 · Forks: 54 - Language: Python - License: not declared - Published: 2026-10-22 · Updated: 2026-10-22 · Language: en - Canonical page: https://hysenlabs.com/projects/valdikss-tor-relay-scanner ## The problem: a Tor client whose built-in relays are unreachable tor-relay-scanner is a Tor relay availability checker, and the project description is explicit about the use case: for using it as a bridge in countries with censorship. The failure mode it addresses is narrow and real. Tor ships with a list of well-known nodes, and those addresses are published, which means a censor with an automated blocklist can block them. A user in that situation can enable Tor's own bridge options, but those are a fixed, small set of transports, and in some networks they are blocked too. What is left is the much larger population of ordinary Tor relays, thousands of which nobody has published as being a bridge, and which a censor has no particular reason to block individually. That is what this script does. The README says it downloads all Tor Relay IP addresses from onionoo.torproject.org, directly and via embedded proxies, and checks whether random Tor relays are reachable from your Internet connection. The readme is equally clear that the point is bypassing the standard well-known nodes embedded into the Tor code, using a working relay as a bridge to connect to the Tor network. So the scope is deliberate. This is not a general proxy scanner and not a credential tool. It reads a public directory of relay addresses, probes them for reachability from your own machine, and hands you the ones that work. The repository is small in the way the task deserves. The top-level listing is a README, a build.sh, a pyproject.toml, a setup.cfg, a src/ directory and a .github/ directory. The pyproject.toml is minimal, with a setuptools build backend requiring setuptools 42 or newer and wheel, and no runtime dependencies listed at all. The licence is recorded as unknown, and the readme carries no licence statement, so the terms of the code are something a reader has to establish rather than assume. Releases are versioned 1.0.x, with 1.0.5 from 2026-07-10, 1.0.4 from 2026-02-03 and 1.0.3 from 2026-01-23, and the last push to the repository was on 2026-10-19. ## With Tor Browser, the working relay is written into prefs.js The primary workflow is aimed at Tor Browser users, and it is a manual step rather than a service. The documentation says it works on Windows and Linux and is not tested on macOS. You download the latest version from the Releases page and put the file into the Tor Browser directory. Then you create a shortcut to it, and the arguments matter: ```bash -g 2 --timeout 3 --browser --start-browser ``` The shortcut is what launches the tool. From then on you start Tor Browser through that shortcut rather than the normal icon, and the tool scans for reachable relays, adds the one it found to the Tor Browser configuration file, prefs.js, and launches the browser. So the output of the scan is not a list for you to copy, it is a configuration change in your browser profile, followed by a normal browser start. The parameter meanings are readable from the names. -g 2 is a group size, -timeout 3 is a per-probe timeout in seconds, --browser selects the browser integration path, and --start-browser launches the browser once a relay has been found. On Linux the shortcut is described as launching the file using python3 with the same arguments, and the readme offers a quicker route to the same result with a shell script: ```bash echo -e '#!/bin/sh\nexec python3' ./tor-relay-scanner-*.pyz '-g 2 --timeout 3 --browser --start-browser' > run.sh && chmod +x run.sh ``` That is the whole Tor Browser flow: fetch, shortcut, run, and the browser opens with a working bridge already configured. ## The daemon path writes a torrc include file instead For a Tor daemon rather than the browser, the tool produces a different artefact. The utility is capable of generating a torrc configuration file containing the Bridge information, and it is launched with these arguments: ```bash --torrc --outfile /etc/tor/bridges.conf ``` The result is a file you then reference from the main configuration. The readme instructs you to append: ```bash %include /etc/tor/bridges.conf ``` to the end of /etc/tor/torrc, so that the Tor daemon loads it. The %include directive keeps the generated bridge list in a separate file, which means the scanner can be re-run and the file rewritten without touching the rest of the daemon's configuration, and the main torrc stays short. The contrast with the browser path is instructive. With Tor Browser, the tool edits prefs.js, a JavaScript file inside a browser profile, and then starts the browser. With the daemon, the tool writes a fragment of torrc and the daemon picks it up on reload. The first path is for a user who wants a one-click fix, the second is for someone running Tor as a service on a server. Both paths share the same underlying search, so the difference is only in what happens to the relay once it has been found. ## Running it standalone, and what the two distribution formats are There is a third use, which is simply running the tool and seeing what it finds. On Windows the readme says to download the .exe file from the Releases page and run it in a console, with the path given as start then cmd. On Linux and macOS you download the .pyz file and run it with Python 3.7 or newer: ```bash python3 tor-relay-scanner.pyz ``` So the project ships two different artefacts for the two platforms, a native executable for Windows and a Python zipapp for the Unix side. The .pyz is a single file, which is what makes the shortcut workflow practical: there is nothing to install and no interpreter setup beyond having Python available, and the .exe removes even that on Windows. The two documented limitations are worth stating plainly. The browser integration is not tested on macOS, which matters because the Tor Browser on macOS is a signed application bundle and modifying its profile is a different operation from dropping a file into a directory. And the Python path needs Python 3.7 or newer, which is a floor rather than a current-version requirement. The fetching mechanism has a detail that explains the design. The script downloads the relay addresses from onionoo.torproject.org both directly and via embedded proxies. A user whose connection is censored may not be able to reach onionoo directly, so the tool carries proxies for the fetch itself, and a user in that situation is exactly the user this project exists for. The scanning then uses random relays rather than walking the list in order, which is the right approach for the same reason: if the first hundred relays on the list are blocked, a sequential scan would stall, and a random sample finds a working one faster. ## Where tor-relay-scanner is the wrong choice The first limitation is that it solves one problem and one problem only. If your Tor client connects without it, the tool adds nothing but a scan of a few hundred relays and a modified browser profile. If your network blocks plain relays and also blocks the ports the relays listen on, a reachability check will report them unreachable, correctly, and you will be no further forward. This tool finds ordinary relays that answer; it does not find obfuscated transports, which is a different problem with different tooling. The second is that the search is local and manual. The readme describes launching the tool from a shortcut each time, which means the result goes stale: the relay that answered today may be blocked tomorrow, and the tool has to be run again. It is a tool for a session, not a supervised service. The third is that it edits your browser profile. The tool writes into prefs.js in the Tor Browser directory, which is a configuration file the browser owns. A profile that has been edited by a third-party script is one that Tor Browser will not warn you about, and if the script and the browser disagree about the format of that file, the result is a browser that will not start cleanly. The daemon path avoids this by using %include in a torrc, which is the safer of the two designs. The fourth is the legal and licence position. The tool's purpose is explicitly to connect to the Tor network in a censored country, which is a legitimate use, and Tor is designed for it. But the repository records no licence at all, and the code is a script that writes into other people's configuration, so an organisation deploying it should establish the terms first. The 1.0.x version line with the last push on 2026-10-19 and a release on 2026-07-10 also suggests a small project maintained by one person, where a bug in the prefs.js writing is a support burden rather than a tracked issue. ## Conclusion tor-relay-scanner fits a user in a country where the standard Tor relays are blocked and the built-in bridge list is not enough, since it tests candidates against your own connection and only registers the ones that answer. It is the wrong choice if your Tor client already connects, and it is the wrong choice if you need something that finds working obfuscated transports rather than plain relays. Before running it, use it the way the documentation describes, as a one-off search rather than a service, and note that the last push was on 2026-10-19 with the newest release tag at 1.0.5 from 2026-07-10. ## FAQ ### What does tor-relay-scanner do? It downloads all Tor relay IP addresses from onionoo.torproject.org, directly and via embedded proxies, and checks whether random Tor relays are reachable from your Internet connection, so a working relay can be used as a bridge where Tor's built-in relays are blocked. ### How do I use tor-relay-scanner with Tor Browser? Download the latest version from the Releases page, put the file into the Tor Browser directory, and create a shortcut to it with the arguments -g 2 --timeout 3 --browser --start-browser. Launching Tor Browser through that shortcut makes the tool scan for a reachable relay, add it to prefs.js and start the browser. It works on Windows and Linux and is not tested on macOS. ### Can tor-relay-scanner generate a torrc file for the Tor daemon? Yes. Run it with --torrc --outfile /etc/tor/bridges.conf, then append %include /etc/tor/bridges.conf to the end of /etc/tor/torrc so the daemon loads the generated bridge information. ### How do I run tor-relay-scanner standalone? On Windows, download the .exe from the Releases page and run it in a console. On Linux and macOS, download the .pyz file and run it with Python 3.7 or newer using python3 tor-relay-scanner.pyz. ### What licence is tor-relay-scanner released under? The project records no licence, and the readme carries no licence statement, so the terms of the code need to be established directly with the maintainer. The last push was on 2026-10-19 and the newest release tag is 1.0.5 from 2026-07-10. ## Sources - [Issues](https://github.com/ValdikSS/tor-relay-scanner/issues) - [README](https://github.com/ValdikSS/tor-relay-scanner/blob/main/README.md) - [Releases](https://github.com/ValdikSS/tor-relay-scanner/releases) - [ValdikSS/tor-relay-scanner on GitHub](https://github.com/ValdikSS/tor-relay-scanner) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/valdikss-tor-relay-scanner