Twisted-based asynchronous Tor control protocol implementation. Includes unit-tests, examples, state-tracking code and configuration abstraction.
Python Other
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
debian fix dependency name Sep 3, 2012
docs Cleanup and fixups so TorState includes reasons on exceptions Jul 18, 2018
examples document aiohttp example May 29, 2018
integration Use __future__.print_function Apr 8, 2017
logo create a logo Dec 10, 2012
scripts better check script for universal wheels Apr 22, 2017
signatues signatures for 18.0.2 Jul 2, 2018
test add test for cancel-before-BUILT case Jul 18, 2018
test3 a python3-only test Mar 14, 2018
twisted/plugins Cleanups and more tests for "tor:" endpoint parser May 31, 2015
txtorcon fix bug Jul 18, 2018
.coveragerc tell covereage where source code is Oct 10, 2015
.gitignore rename tox virtualenv's and gitignore them Feb 3, 2015
.travis.yml upgrade pip for travis (trying to fix 3.4 builders) Aug 2, 2018
Dockerfile fix Dockerfile and integration tests Jan 17, 2017
INSTALL dev-requirements too Mar 11, 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 18.0.2 version bump Jul 2, 2018
README.rst PyPI is sad about any duplicate targets in README...hmmm Mar 26, 2018
TODO remove irrelevant TODOs Sep 26, 2012
dev-requirements.txt pep8 -> pycodestyle Jun 18, 2018
docs-requirements.txt docs need automat Feb 2, 2017
meejah.asc initial import Feb 29, 2012
requirements.txt Make ipaddress a conditional dependency. (Closes: #247) Jan 1, 2018 Don't install global test package Apr 4, 2018
tox.ini add 3.4 to tox config Jul 2, 2018


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

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).