🧅 hypertor

Tor for Python. Make HTTP requests over the Tor network, and host onion services.

No Tor daemon required — hypertor speaks the Tor protocol itself, through arti, the Tor Project's Rust implementation.

pip install hypertor

import hypertor

with hypertor.Client() as client:
    response = client.get("https://check.torproject.org/api/ip")
    print(response.json())

Requests

client = hypertor.Client(
    timeout=60.0,                     # seconds, covers the whole request
    isolation="per_host",             # "none" | "per_host" | "per_request"
    max_response_size=16 * 1024**2,   # applies to the decoded body
    verify=True,
)

client.get(url, params={"q": "rust"}, headers={"X-Custom": "value"})
client.post(url, json={"name": "Alice"})
client.post(url, data={"field": "value"})       # form-urlencoded
client.request("PROPFIND", url)

response.status_code, response.ok, response.text, response.content
response.json()
response.raise_for_status()

Constructing a Client bootstraps Tor, which takes tens of seconds on a cold cache. Create one and reuse it. Every network call releases the GIL, so a slow request never freezes the rest of your program.

AsyncClient exposes exactly the same methods, awaitable:

async with hypertor.AsyncClient() as client:
    responses = await asyncio.gather(
        client.get("http://a.onion/"),
        client.get("http://b.onion/"),
    )

Circuit isolation

Two requests sharing a Tor circuit leave the network from the same exit relay at the same moment, and are linkable by anyone watching it. Isolation decides which of your activities may be linked.

alice = hypertor.IsolationToken()
bob = hypertor.IsolationToken()

client.get("http://forum.onion/inbox", isolation=alice)
client.get("http://forum.onion/profile", isolation=alice)   # same circuit
client.get("http://shop.onion/cart", isolation=bob)         # never the same circuit

Hosting an onion service

app = hypertor.OnionApp("my-service", state_dir="./onion-state")

@app.get("/")
def home(request):
    return "<h1>hello from .onion</h1>"

@app.get("/users/{user_id}")
def get_user(request):
    user = lookup(request.params["user_id"])
    if user is None:
        return {"error": "no such user"}, 404          # Flask-style (body, status)
    return user, 200, {"cache-control": "no-store"}

app.run()   # prints the .onion address, then serves until Ctrl-C

The nickname is the identity: the .onion address is derived from a key filed under it, so relaunching with the same nickname republishes the same address.

Errors

except hypertor.TimeoutError: ...
except hypertor.ConnectionError: ...      # bootstrap or connect failure
except hypertor.TlsError: ...
except hypertor.StatusError: ...          # non-2xx from raise_for_status
except hypertor.HypertorError: ...        # catches all of the above

Hostnames are scrubbed from error messages, because error messages end up in logs.

Type hints

The package ships py.typed and complete stubs, so mypy and pyright check your usage.

Documentation

Full docs: https://hupe1980.github.io/hypertor/docs/python/

The Rust library lives at crates.io/crates/hypertor and carries no Python dependency; these bindings are built from bindings/python in the repository.

A word of caution

hypertor is not an anonymity system in its own right, and no library can be. Tor protects the network path; it cannot protect you from an application that logs in with your real identity, from timing patterns in your own traffic, or from a compromised machine. Read the Tor Project's guidance before relying on this for anything that matters. Not affiliated with, endorsed by, or sponsored by the Tor Project.

License

MIT.

Project links

Data verified by PyPI on Aug 15, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for hupe1980 from gravatar.com hupe1980

Credits

Author: hupe1980

GitHub Statistics

Data verified by PyPI on Aug 15, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.10

Provides Extra

dev

Tags

tor http privacy anonymity onion hidden-service

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hypertor-0.3.0.tar.gz (286.5 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

hypertor-0.3.0-cp310-abi3-win_amd64.whl (10.1 MB view details)

Uploaded CPython 3.10+Windows x86-64

hypertor-0.3.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (10.0 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ x86-64

hypertor-0.3.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (9.7 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ ARM64

hypertor-0.3.0-cp310-abi3-macosx_11_0_arm64.whl (9.5 MB view details)

Uploaded CPython 3.10+macOS 11.0+ ARM64

hypertor-0.3.0-cp310-abi3-macosx_10_12_x86_64.whl (9.8 MB view details)

Uploaded CPython 3.10+macOS 10.12+ x86-64

File details

Details for the file hypertor-0.3.0.tar.gz.

File metadata

  • Download URL: hypertor-0.3.0.tar.gz
  • Upload date:
  • Size: 286.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for hypertor-0.3.0.tar.gz
Algorithm Hash digest
SHA256 89ddb02cdc884b3dd7ae927e319328a72133beea3b11c36f7a376f692880d7e7
MD5 5b631d2f7347c2bd8f941aadaa66e0cf
BLAKE2b-256 909d79e5799a585a578fdd6636e5edc35f9f96a58beab810acebf47e51ebbbc8

See more details on using hashes here.

Provenance

The following attestation bundles were made for hypertor-0.3.0.tar.gz:

Publisher: release.yml on hupe1980/hypertor

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file hypertor-0.3.0-cp310-abi3-win_amd64.whl.

File metadata

  • Download URL: hypertor-0.3.0-cp310-abi3-win_amd64.whl
  • Upload date:
  • Size: 10.1 MB
  • Tags: CPython 3.10+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for hypertor-0.3.0-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 261cf397d3a353bbff6788b7f1c86ba32e85bf669d98736b01d7189092ed108c
MD5 a85cc1eb1e17a3ccb566d59e6ccb34d6
BLAKE2b-256 db8ba456abdda260cce6b975b6c91b08034789eec119362a6e6b8f7a628d8470

See more details on using hashes here.

Provenance

The following attestation bundles were made for hypertor-0.3.0-cp310-abi3-win_amd64.whl:

Publisher: release.yml on hupe1980/hypertor

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file hypertor-0.3.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for hypertor-0.3.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 c8bff54d5d8587faa6d56f69a8614e26516d07fa68c0e4733c8fc8f579d91da6
MD5 f22080ec3ad712d0317552bad101c3ff
BLAKE2b-256 e3b74d697cd1c475bf364a226d9c343f01bdfcdc6bdfdaeeceb337be52c66faf

See more details on using hashes here.

Provenance

The following attestation bundles were made for hypertor-0.3.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on hupe1980/hypertor

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file hypertor-0.3.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for hypertor-0.3.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 e7f5e09d767767d9228262dd25c4793b6c1d68066b2c9f2788940547a5a3ac3a
MD5 61e7d62d673c0c5d43689e873ccc206b
BLAKE2b-256 a9438669d3b17d15334718a6eb34ae378d53fa523fb1b88ec3730f784d7f6f46

See more details on using hashes here.

Provenance

The following attestation bundles were made for hypertor-0.3.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on hupe1980/hypertor

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file hypertor-0.3.0-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for hypertor-0.3.0-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 635d950c9da02c7f0d86a3d2e9ae90491b6dc5d1b53c0df0b3aa6d0e0a725c93
MD5 48f1e3d1eb6f7b0f7599616d0b6dc1f0
BLAKE2b-256 5f0893b19725c4b960fa74a1bc69bcf891399839ce236ec24b1c1ac8d946ee61

See more details on using hashes here.

Provenance

The following attestation bundles were made for hypertor-0.3.0-cp310-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on hupe1980/hypertor

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file hypertor-0.3.0-cp310-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for hypertor-0.3.0-cp310-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 f5c785ff45a67787f3e7f090039be89926bb653d280bb87e842fd3d3010705bf
MD5 c2f1b85dbc85ad1d9365ed97d725d762
BLAKE2b-256 7bb829fb61ef85a568136bcf2d352dfa3aa11b28987217e43b204bca8baacde6

See more details on using hashes here.

Provenance

The following attestation bundles were made for hypertor-0.3.0-cp310-abi3-macosx_10_12_x86_64.whl:

Publisher: release.yml on hupe1980/hypertor

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.3.0 This release

6 files

0.2.2

5 files

0.2.1

5 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page