If this is your first time using a Tor controller library, you’re in the right spot. I presume at least some familiarity with Twisted and asynchronous programming.

What We’ll Learn

In this tutorial, I will go through several examples building up a small program. We will:

  • connect to a running Tor;
  • launch our own Tor;
  • change the configuration;
  • get some information from Tor;
  • listen for events;
  • and send a NEWNYM signal.

All the code examples are also in the walkthrough directory.

Install txtorcon in a virtualenv

First we need to be able to import txtorcon in a Python shell. We will accomplish that in a virtualenv.


If you’re using Debian or Ubuntu, pip install python-txtorcon may just work.

To try the latest released version of txtorcon in a virtualenv is similar to other Python packages:

virtualenv /tmp/txtorcon-venv
/tmp/txtorcon-venv/bin/pip install txtorcon
source /tmp/txtorcon-venv/bin/activate

You should now be able to run “import txtorcon” in a python shell, for example:

python -c "import txtorcon"

The above should produce no output. If you got an exception, or something else went wrong, read up on virtualenv or ask “meejah” in #tor-dev for help.

Connect to a Running Tor

If you’ve got a system-wide Tor running, it defaults to port 9051 if you have the control interface turned on. /etc/tor/torrc should contain lines similar to this:

ControlPort 9051
CookieAuthentication 1

Alternatively, if you’re currently running the Tor Browser Bundle, it defaults to a port of 9151 and doesn’t turn on cookie authentication. Change the options to turn on cookie authentication and change “9051” to “9151” in the following examples.

We will use the txtorcon.build_tor_connection() API call, which returns a Deferred that callbacks with a TorControlProtocol or TorState instance (depending on whether the build_state kwarg was True – the default – or False).

The TorState instance takes a second or two to get built as it queries Tor for all the current relays and creates a Router instance of which there are currently about 5000. TorControlProtocol alone is much faster (dozens of milliseconds).

The code to do this would look something like:

from __future__ import print_function
from twisted.internet.task import react
from twisted.internet.defer import inlineCallbacks
from twisted.internet.endpoints import TCP4ClientEndpoint
import txtorcon

def main(reactor):
    # change the port to 9151 for Tor Browser Bundle
    connection = TCP4ClientEndpoint(reactor, "localhost", 9051)

    state = yield txtorcon.build_tor_connection(connection)
    print("Connected to tor {state.protocol.version}".format(state=state))
    print("Current circuits:")
    for circ in state.circuits.values():
        path = '->'.join([r.name for r in circ.path])
        print("  {circ.id}: {circ.state}, {path}".format(circ=circ, path=path))

    # can also do "low level" things with the protocol
    proto = state.protocol
    answer = yield proto.queue_command("GETINFO version")
    print("GETINFO version: {answer}".format(answer=answer))


If all is well, you should see some output like this:

python walkthrough/0_connection.py
Connected to tor (git-3731dd5c3071dcba)
Current circuits:
  16929: BUILT, someguard->ecrehd->aTomicRelayFR1
  16930: BUILT, someguard->Ferguson->NLNode1EddaiSu
GETINFO version: version= (git-3731dd5c3071dcba)

Launch Our Own Tor

For some use-cases you will want to launch a private Tor instance. txtorcon provides txtorcon.launch_tor() to do just that. This also uses some Tor commands to link the controller to the Tor instance, so that if the connection is lost Tor will shut itself down.

The main difference between connecting and launching is that you have to provide a configuration to launch Tor with. This is provided via a TorConfig instance. This class is a little “magic” in order to provide a nice API, and so you simply set configuration options as members. A minimal configuration to launch a Tor might be:

config = txtorcon.TorConfig()
config.ORPort = 0
config.SocksPort = 9999

The launch_tor method itself also adds several necessary configuration options but only if they aren’t supplied already. For example, if you want to maintain state (or hidden service keys) between launches, provide your own DataDirectory. The configuration keys launch_tor adds are:

  • DataDirectory a mkdtemp directory in /tmp/ (which is deleted at exit, unless it was user-specified)
  • ControlPort is set to 9052 unless already specified
  • CookieAuthentication is set to 1
  • __OwningControllerProcess is set to our PID

Check out the txtorcon.launch_tor() documentation. You’ll likely want to provide a progress_updates listener to provide interesting information to your user. Here’s a full example:

#!/usr/bin/env python

from __future__ import print_function
import os
from twisted.internet.defer import inlineCallbacks
from twisted.internet.task import react
from twisted.internet.endpoints import TCP4ClientEndpoint
import txtorcon

def progress(percent, tag, summary):
    Progress update from tor; we print a cheezy progress bar and the
    ticks = int((percent/100.0) * 10.0)
    prog = (ticks * '#') + ((10 - ticks) * '.')
    print('{} {}'.format(prog, summary))

def main(reactor):
    config = txtorcon.TorConfig()
    config.ORPort = 0
    config.SocksPort = 9998
    except OSError:
    config.DataDirectory = './tor-data'

        process = yield txtorcon.launch_tor(
            config, reactor, progress_updates=progress
    except Exception as e:
        print("Error launching tor:", e)

    protocol = process.tor_protocol
    print("Tor has launched.")
    print("Protocol:", protocol)
    info = yield protocol.get_info('traffic/read', 'traffic/written')

    # explicitly stop tor by either disconnecting our protocol or the
    # Twisted IProcessProtocol (or just exit our program)
    print("Killing our tor, PID={pid}".format(pid=process.transport.pid))
    yield process.transport.signalProcess('TERM')


If you’ve never seen the inlineCallbacks decorator, then you should read up on it. Once we get the Tor instance launched, we just make two GETINFO calls and then explicitly kill it. You can also simply exit, which will cause the underlying Tor to also exit.

Putting It All Together

So, now we’ve gotten a basic connection to Tor (either by launching one or connecting to a running one) and basically done nothing but exit.

Let’s do something slightly more interesting. We will connect to a running Tor (like the first example), issue the NEWNYM signal (which tells Tor to no longer use any existing circuits for new connections) and then continuously monitor two events: circuit events via TorState interfaces and INFO messages via a raw add_event_listener.

First, we add a simple implementation of txtorcon.ICircuitListener:

class MyCircuitListener(object):

    def circuit_new(self, circuit):
        print("\n\nnew", circuit)

    def circuit_launched(self, circuit):
        print("\n\nlaunched", circuit)

    def circuit_extend(self, circuit, router):
        print("\n\nextend", circuit)

    def circuit_built(self, circuit):
        print("\n\nbuilt", circuit)

    def circuit_closed(self, circuit, **kw):
        print("\n\nclosed", circuit, kw)

    def circuit_failed(self, circuit, **kw):
        print("\n\nfailed", circuit, kw)

Next, to illustrate setting up TorState from a TorControlProtocol directly we first make a “bare” protocol connection, and then use a TorState classmethod (with the protocol instance) to query Tor’s state (this instance also adds listeners to stay updated).

Then we use TorControlProtocol.signal to send a NEWNYM request. After that we create a TorState instance, print out all existing circuits and set up listeners for circuit events (an instance of MyCircuitListener) and INFO messages (via our own method).

Note there is a :class:`txtorcon.CircuitListenerMixin`_ class – and similar interfaces for :class:`txtorcon.Stream`_ as well – which makes it easier to write a listener subclass.

Here is the full listing:

from __future__ import print_function
from twisted.internet.task import react
from twisted.internet.defer import inlineCallbacks, Deferred
from twisted.internet.endpoints import TCP4ClientEndpoint
from zope.interface import implementer
import txtorcon

class MyCircuitListener(object):

    def circuit_new(self, circuit):
        print("new", circuit)

    def circuit_launched(self, circuit):
        print("launched", circuit)

    def circuit_extend(self, circuit, router):
        print("extend", circuit)

    def circuit_built(self, circuit):
        print("built", circuit)

    def circuit_closed(self, circuit, **kw):
        print("closed", circuit, kw)

    def circuit_failed(self, circuit, **kw):
        print("failed", circuit, kw)

def main(reactor):
    # change the port to 9151 for Tor Browser Bundle
    tor_ep = TCP4ClientEndpoint(reactor, "localhost", 9051)
    connection = yield txtorcon.build_tor_connection(tor_ep, build_state=False)
    version = yield connection.get_info('version', 'events/names')
    print("Connected to Tor {version}".format(**version))
    print("Events:", version['events/names'])

    print("Building state.")
    state = yield txtorcon.TorState.from_protocol(connection)

    print("listening for circuit events")

    print("Issuing NEWNYM.")
    yield connection.signal('NEWNYM')

    print("Existing circuits:")
    for c in state.circuits.values():
        print(' ', c)

    print("listening for INFO events")
    def print_info(i):
        print("INFO:", i)
    connection.add_event_listener('INFO', print_info)

    done = Deferred()
    yield done  # never callback()s so infinite loop


If your Tor instance has been dormant for a while, try something like torsocks curl https://www.torprojec.org in another termainl so you can see some more logging and circuit events.