OnionShare Guide — Share Files Anonymously Over Tor

Sharing Files Over Tor: A Practical Guide to OnionShare

When you need to move a file from point A to point B without exposing your IP address, your location, or your metadata to intermediaries, the conventional options—email, cloud storage, instant messaging—all fail. Every one of them logs something. Even end-to-end encrypted services often expose the fact that you are communicating with a particular server or peer. For researchers, journalists, and privacy-conscious operators who work with sensitive data, the requirement is not just encryption; it is anonymity of the sender and the receiver. This is where OnionShare enters the picture. Built on top of the Tor network, OnionShare turns your local machine into a temporary, ephemeral .onion service that a recipient can access directly through the Tor Browser. There is no middleman server, no file is stored on a third-party platform, and the transfer itself is encrypted end to end. The core design is simple, but the operational security considerations are not. This guide walks through installation, configuration, realistic threat models, and the common pitfalls that can expose a user who gets sloppy.

What OnionShare Is and How It Works

OnionShare is an open-source tool that creates a Tor hidden service directly from your computer. When you share a file or a folder, OnionShare spins up a local web server that binds only to 127.0.0.1—exactly as a properly configured hidden service should, as highlighted in research on misconfigurations that expose real IP addresses. That local server is then exposed as a .onion address through Tor’s onion service protocol. The recipient, who must also be using Tor Browser, navigates to that .onion address and downloads the file directly from your machine. No traffic passes through a commercial server, no logs are generated on a third-party platform, and the Tor network ensures that neither the sender nor the receiver knows the other’s real IP address. The file transfer itself is encrypted using the Tor circuit, which wraps the data in layers of encryption that are peeled away at each relay—a technique derived from the original onion routing research conducted at the U.S. Naval Research Laboratory in the mid-1990s by Paul Syverson, Michael G. Reed, and David Goldschlag. OnionShare implements this without the complexity of manually configuring a web server, making it accessible to non-experts while retaining a high degree of technical rigor.

Installation and First Steps

OnionShare is available for Windows, macOS, and Linux. On Debian-based distributions, you can add the official repository and install via apt. For macOS, the official .dmg installer works cleanly. Windows users can download the installer from the official website. Once installed, the interface is minimalist: you drag in a file or a folder, click “Start Sharing,” and OnionShare generates a .onion URL that you then transmit to your recipient through a side channel—Signal, PGP-encrypted email, or another secure method. Never paste the .onion link into an unencrypted channel like SMS or cleartext email, because if an adversary intercepts that link, they can also download the file. The tool also supports “Receive” mode, where you generate a .onion URL that allows others to upload files to your machine. This is useful for secure drop boxes, but it also means your machine must be online and connected to Tor for the duration of the receive window. For persistent needs, it is worth noting that some operators run OnionShare on a dedicated, minimal server that stays online 24/7, but that introduces a different risk profile — you are now running a hidden service, and misconfigurations can lead to deanonymization.

Threat Model: What OnionShare Defends Against

It is critical to be honest about what OnionShare does and does not protect you from. OnionShare defends against:

• Network-level surveillance: An ISP, employer, or government monitoring your internet connection cannot see that you are transferring a file, only that you are using Tor.
• Server compromise: Since there is no intermediary server, there is no server to subpoena.
• Metadata leakage: No cloud provider logs your upload time, file size, or recipient IP.

It does not defend against:

• Compromise of either endpoint. If your machine has malware, a keylogger, or an insecure configuration, all bets are off.
• Traffic correlation attacks. If an adversary can observe traffic at both your ISP and the recipient’s ISP simultaneously, they can potentially correlate timing patterns. This is a known limitation of onion routing, where timing analysis can break anonymity.
• Poor OPSEC. If you share the .onion link in a channel that is monitored, or if you leave a file on your desktop with identifying metadata, the tool cannot save you.

For most threat models — a journalist sharing documents with a source, a researcher distributing data to a colleague, a patient reporting a security finding — OnionShare is sufficient. For state-level adversaries capable of global passive surveillance, additional layers of operational security are required, including the use of Tails or a Whonix gateway to isolate the process from the host operating system.

Operational Security Considerations

The single most common mistake when using OnionShare is treating it as a “fire and forget” tool. Here is a checklist of OPSEC rules that should be second nature:

• Strip metadata from files before sharing. Photos often contain EXIF data with GPS coordinates. Office documents can contain author names and revision history. Use a tool like exiftool or mat2 to remove metadata before dragging the file into OnionShare.
• Use a dedicated, isolated environment. Running OnionShare on your daily-driver machine is risky. If your browser, email client, or any other software leaks your real IP (for example, through WebRTC or a DNS leak), the entire setup is compromised. Ideally, use Tails or a Whonix workstation where all traffic is forced through Tor.
• Set a persistent address. OnionShare can generate a persistent .onion address secured by a private key that you keep. This allows you to reuse the same link across sessions. However, reusing the same address creates a pattern that can be tracked, and if the private key is ever leaked, an adversary can impersonate your service.
• Close the share immediately after transfer. Do not leave the share running overnight. The longer it is online, the greater the window for timing analysis or passive observation.
• Use the “Stop sharing automatically” feature. OnionShare can be configured to stop sharing after the first download. This reduces the risk of an unwanted second download by an unauthorized party.

Backend Configuration and Advanced Usage

For users who are comfortable with the command line, OnionShare offers a CLI mode that can be scripted. This is particularly useful for integrating file sharing into automated workflows—for example, a periodic data drop script that uploads a CSV to a recipient’s drop box. The CLI accepts flags for port, timeout, and persistent address generation. Under the hood, OnionShare uses the same Tor control protocol that any hidden service uses. It creates a hidden service descriptor that registers with the Tor network’s distributed hash table, and the web server is a lightweight Python-based HTTP server. OnionShare can also be configured to use a custom Tor control port, which allows it to be used with a system-wide Tor daemon rather than the bundled one. This is useful in advanced setups where you want to route the transfer through your own Tor instance, perhaps with bridges or a custom exit policy.

A Common Pitfall: The Certificate Transparency Risk

One of the less obvious risks that applies to any hidden service, including OnionShare, is the mismanagement of TLS certificates. OnionShare does not use a public TLS certificate by default—it relies on the encryption provided by the Tor circuit. However, some advanced users choose to add a TLS certificate to their OnionShare instance, perhaps to prevent a browser warning about the .onion address. This is a mistake. When you obtain an SSL certificate from a certificate authority like Let’s Encrypt or Comodo, that certificate is logged in public Certificate Transparency logs. If the same certificate is used on both the OnionShare service and a clearnet server, or if the certificate’s Subject Alternative Names include a clearnet domain, the link between the .onion address and your real identity becomes trivial to establish using a searchable tool like crt.sh. Do not add a TLS certificate to an OnionShare service unless you have a very specific threat model that justifies the risk, and even then, use a certificate that is unique to the .onion address and never reused anywhere.

Alternatives and Limitations

OnionShare is not a magic bullet. The maximum file size is limited by your available RAM and the patience of your recipient—a 2 GB file will take a long time to transfer through Tor because of the latency added by the circuit. For extremely large files, consider splitting them into chunks or using a different tool like Syncthing over a VPN, though the anonymity properties will differ. OnionShare is also strictly point-to-point; there is no mechanism for broadcasting a file to multiple recipients simultaneously (though you have to share the link multiple times, each recipient connects directly to your machine). For scenarios where you need a high-availability repository of files that multiple users can access asynchronously, a more robust solution is to set up a dedicated Tor hidden service with a properly configured web server. But for one-off transfers that require anonymity, OnionShare remains the most straightforward and reliable tool available.

Final Verdict

OnionShare occupies a specific niche: it is the closest thing to a “burner phone” for file transfers. It is ephemeral, anonymous, and leaves no trace on either end if used correctly. The barrier to entry is low, but the operational discipline required is not. Misconfigurations—leaving a share running too long, reusing a .onion address, failing to strip metadata, or adding a TLS certificate—can turn a secure transfer into an investigation lead. For researchers, journalists, and anyone who handles sensitive data on the darknet, OnionShare is an essential tool when used within the limits of its threat model. Install it, test it on a low-stakes file first, and internalize the OPSEC checklist before you trust it with anything that matters.