Twisted-based asynchronous Tor control protocol implementation. Includes unit-tests, examples, state-tracking code and configuration abstraction.
Python Other
Latest commit 1981a81 Feb 17, 2017 @meejah fix newconsensus properly
Failed to load latest commit information.
debian fix dependency name Sep 3, 2012
docs link to travis Feb 17, 2017
examples move example to a proper 'listing' Feb 14, 2017
integration fix Dockerfile and integration tests Jan 17, 2017
logo create a logo Dec 10, 2012
scripts check hidden-service binaries Oct 4, 2016
signatues signatures for 0.18.0 Jan 11, 2017
test fix newconsensus properly Feb 17, 2017
twisted/plugins Cleanups and more tests for "tor:" endpoint parser May 31, 2015
txtorcon fix newconsensus properly Feb 17, 2017
.coveragerc tell covereage where source code is Oct 10, 2015
.gitignore rename tox virtualenv's and gitignore them Feb 3, 2015
.travis.yml make travis do more work Feb 16, 2017
Dockerfile fix Dockerfile and integration tests Jan 17, 2017
INSTALL Add a top-level Tor API object and web client support Feb 1, 2017
LICENSE Include LICENSE in manifest, and add 2013 to copyright dates (issue #53) May 18, 2013 ignore .pyc, fixing issue #76 Jun 16, 2014
Makefile Add a top-level Tor API object and web client support Feb 1, 2017
README.rst fix doc badges Feb 16, 2017
TODO remove irrelevant TODOs Sep 26, 2012
dev-requirements.txt use 'cuv graph' instead of c'coverage report' Jan 17, 2017
docs-requirements.txt docs need automat Feb 2, 2017
meejah.asc initial import Feb 29, 2012
requirements.txt Import `Twisted[tls]` and `automat` Feb 11, 2017 whitespace, pep8 and metadata improvements for Oct 25, 2015
tox.ini add twisted 17.1 to tox Feb 16, 2017


travis coveralls codecov ReadTheDocs ReadTheDocs flattr Code Health



Several large, new features have landed on master. If you're working directly from master, note that some of these APIs may change before the next release.

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


from twisted.internet.task import react
from twisted.internet.defer import inlineCallbacks
from twisted.internet.endpoints import TCP4ClientEndpoint
import treq  # 'like requests, but for twisted'
import txtorcon

def main(reactor):

    def update(percent, tag, summary):
        print("{}%: {}".format(int(percent), summary))
    tor = yield txtorcon.launch(

    print("Tor started: {}".format(tor))

    # make a request via Tor
    resp = yield treq.get(

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

    # create a new circuit
    print("creating 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])))

    # make a request via our new circuit
    print("Downloading meejah's public key...")
    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 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).