Skip to main content
Join the official 2019 Python Developers SurveyStart the survey!

Twisted-based Tor controller client, with state-tracking and configuration abstractions.

Project description

travis coveralls codecov ReadTheDocs ReadTheDocs Code Health


Ten Thousand Feet

txtorcon is an implementation of the control-spec for Tor using the Twisted networking library for Python.

This is useful for writing utilities to control or make use of Tor in event-based Python programs. If your Twisted program supports endpoints (like twistd does) your server or client can make use of Tor immediately, with no code changes. Start your own Tor or connect to one and get live stream, circuit, relay updates; read and change config; monitor events; build circuits; create onion services; etcetera (ReadTheDocs).

Some Possibly Motivational Example Code

download (also python3 style)

from twisted.internet.task import react
from twisted.internet.defer import inlineCallbacks
from twisted.internet.endpoints import UNIXClientEndpoint
import treq
import txtorcon

def main(reactor):
    tor = yield txtorcon.connect(
        UNIXClientEndpoint(reactor, "/var/run/tor/control")

    print("Connected to Tor version {}".format(tor.version))

    url = ''
    print("Downloading {}".format(url))
    resp = yield treq.get(url, agent=tor.web_agent())

    print("   {} bytes".format(resp.length))
    data = yield resp.text()
    print("Got {} bytes:\n{}\n[...]{}".format(

    print("Creating a circuit")
    state = yield tor.create_state()
    circ = yield state.build_circuit()
    yield circ.when_built()
    print("  path: {}".format(" -> ".join([r.ip for r in circ.path])))

    print("Downloading meejah's public key via above circuit...")
    resp = yield treq.get(
        agent=circ.web_agent(reactor, tor.config.socks_endpoint(reactor)),
    data = yield resp.text()

Try It Now On Debian/Ubuntu

For example, serve some files via an onion service (aka hidden service):

$ sudo apt-get install --install-suggests python-txtorcon
$ twistd -n web --port "onion:80" --path ~/public_html

Read More

All the documentation starts in docs/index.rst. Also hosted at

You’ll want to start with the introductions (hosted at RTD).

Project details

Download files

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

Files for txtorcon, version 19.1.0
Filename, size File type Python version Upload date Hashes
Filename, size txtorcon-19.1.0-py2.py3-none-any.whl (341.0 kB) File type Wheel Python version py2.py3 Upload date Hashes View hashes
Filename, size txtorcon-19.1.0.tar.gz (312.7 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page