The Tor Browser anonymizes web browsing using multi-hop network routing featuring layered encryption (the “Onion network”). You can picture it like that trope in action movies where they’re tracing a network intrusion back through multiple server locations scattered all over a world map. (Except that the reverse tracing isn’t a thing and the Onion network’s encryption prevents any meaningful interception.)
The browser can access regular websites as well as hidden Onion sites operated inside the Onion network. Onion sites try to anonymize both the server and the visitor. Onion sites are addressed using cryptographic hashes — long random-looking strings of letters and numbers — instead of domain names and IP addresses. This presents a usability issue as they’re nearly impossible for humans to remember. For example, the “ctrl.blog” domain name is more human-friendly and memorable than the blog’s Onion site address at “ctrlxsbxudan5eq7742bxk4wgp6j4vhp7y2xbml5vdvhznicl7h6taid.onion.”
Until now, there hasn’t been a standard method to discover a website’s Onion site from the main website. That changed with the new release of Tor Browser version 9.5. It introduced a new Onion-Location HTTP response header. Websites can include this response header and have it include a link to the Onion site. The header should including the Onion site origin, plus the same path and query parameter as the current request.
The Tor Browser will display a “.onion available” button (the purple button seen at the top of the article) in the address field for encrypted websites (HTTPS) that includes the new header. Clicking it will redirect the user to the same webpage on the Onion site. The first time a user encounters this button, they’re also prompted if they want to automatically be redirected to Onion sites when one is available.
The new button is currently only available in Tor Browser for Linux, MacOS, and Windows. It isn’t [yet] supported in Tor Browser for Android.
Update (): Both Brave for Linux, MacOS, and Windows; and Onion Browser for iOS has added support for Onion-Location. Neither browsers are affiliated with the Tor Project, but can connect to the Tor Onion network.
The Tor Project has published documentation on how to implement an Onion-Location response header using popular web servers. You can alternatively use a <meta> element on webpages if you don’t control the web server. If you’re using the Apache HTTPD Server, you may also want to read my article on cleaning up the REQUEST_URI variable for subrequests.
I crawled the top 1 million domain names (from the Tranco List) on and found 30 websites that issued the Onion-Location response header. (You can get the full list of discovered Onion sites below.) Only three websites had opted for using the alternative <meta> auto-discovery method, and only one of those also hadn’t configured the HTTP response header. Five websites were served using the Apache HTTPD Server and every one — including the Tor Project website itself – showed signs of problems with their REQUEST_URI variable.
Only eight of the sites I discovered during the crawl were listed in the Real World Onion Sites project’s directory of Onion sites. Notable websites such as The New York Times, Internet Archive, Facebook, and BBC News don’t yet promote their Onion sites with the Onion-Location response header. The feature is three weeks old so this maybe isn’t too surprising. I expect to see adoption grown in the coming months.
The new response header will make it easier to map domain names to their corresponding Onion site. This can help projects like Real World Onion Sites map popular websites on the internet onto the Onion network. Search engines with an Onion site presences — including Cliqz Search and DuckDuckGo — can choose to link directly to the Onion site instead of the regular website for visitors using the Onion network. This improves security and page-load performance. Cliqz Search already does this to a limited extent using the curated directory maintained by Real World Onion Sites.