by meejah

meejah / txtorcon

Twisted-based asynchronous Tor control protocol implementation. Includes unit-tests, examples, state...

208 Stars 62 Forks Last release: 7 months ago (v20.0.0) MIT License 1.7K Commits 39 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

.. _NOTE: see docs/index.rst for the starting-point .. _ALSO: https://txtorcon.readthedocs.org for rendered docs

.. image:: https://travis-ci.org/meejah/txtorcon.png?branch=main :target: https://www.travis-ci.org/meejah/txtorcon :alt: travis

.. image:: https://coveralls.io/repos/meejah/txtorcon/badge.png :target: https://coveralls.io/r/meejah/txtorcon :alt: coveralls

.. image:: http://codecov.io/github/meejah/txtorcon/coverage.svg?branch=main :target: http://codecov.io/github/meejah/txtorcon?branch=main :alt: codecov

.. image:: https://readthedocs.org/projects/txtorcon/badge/?version=stable :target: https://txtorcon.readthedocs.io/en/stable :alt: ReadTheDocs

.. image:: https://readthedocs.org/projects/txtorcon/badge/?version=latest :target: https://txtorcon.readthedocs.io/en/latest :alt: ReadTheDocs

.. image:: https://landscape.io/github/meejah/txtorcon/main/landscape.svg?style=flat :target: https://landscape.io/github/meejah/txtorcon/main :alt: Code Health


  • docs: https://txtorcon.readthedocs.org or http://timaq4ygg2iegci7.onion
  • code: https://github.com/meejah/txtorcon
  • torsocks git clone git://timaq4ygg2iegci7.onion/txtorcon.git
  • MIT-licensed;
  • Python 2.7, PyPy 5.0.0+, Python 3.5+;
  • depends on
    , (and the
    _ backport for non Python 3)

Ten Thousand Feet

txtorcon is an implementation of the

_ for
_ using the
_ networking library for

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

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 (

Some Possibly Motivational Example Code

_ (also
python2 style 

.. code:: python

from twisted.internet.task import react
from twisted.internet.defer import inlineCallbacks, ensureDeferred
from twisted.internet.endpoints import UNIXClientEndpoint

import treq import txtorcon

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

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

url = u'https://www.torproject.org:443'
print(u"Downloading {}".format(repr(url)))
resp = await treq.get(url, agent=tor.web_agent())

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

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

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

@react def _main(reactor): return ensureDeferred(main(reactor))

Try It Now On Debian/Ubuntu

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

.. code-block:: shell-session

$ sudo apt-get install --install-suggests python3-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

.. _Twisted: https://twistedmatrix.com/trac

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.