Awesome Open Source
Awesome Open Source

.. _NOTE: see docs/index.rst for the starting-point .. _ALSO: for rendered docs

.. image:: :target: :alt: travis

.. image:: :target: :alt: coveralls

.. image:: :target: :alt: codecov

.. image:: :target: :alt: ReadTheDocs

.. image:: :target: :alt: ReadTheDocs

.. image:: :target: :alt: 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 <examples/>_ (also python2 style <examples/>_)

.. 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(
        UNIXClientEndpoint(reactor, "/var/run/tor/control")

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

    url = u''
    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()

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 <docs/index.rst>. Also hosted at <>.

You'll want to start with the introductions <docs/introduction.rst>_ (hosted at RTD <>_).

.. _Twisted:

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
python (50,967
async (464
privacy (374
tor (115
twisted (28
async-programming (15

Find Open Source By Browsing 7,000 Topics Across 59 Categories