Skip to main content

Twisted-based Tor controller client, with state-tracking and configuration abstractions.

Project description

Author: meejah
License: MIT

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

.. image::
:alt: travis

.. image::
:alt: coveralls

.. image::
:alt: codecov

.. image::
:alt: ReadTheDocs

.. image::
:alt: ReadTheDocs

.. image::
:alt: flattr

.. image::
:alt: Code Health


- **docs**: or http://timaq4ygg2iegci7.onion
- **code**:
- ``torsocks git clone git://timaq4ygg2iegci7.onion/txtorcon.git``
- MIT-licensed;
- Python 2.7, PyPy 5.0.0+, Python 3.4+;
- depends on
`Automat <>`_,
(and the `ipaddress <>`_ backport for non Python 3)

.. caution::

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 <examples/>`_
(also `python3 style <examples/>`_)

.. code:: python

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

.. code-block:: shell-session

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

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

.. _Twisted:

Keywords: python,twisted,tor,tor controller
Platform: UNKNOWN
Classifier: Framework :: Twisted
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: Proxy Servers
Classifier: Topic :: Internet
Classifier: Topic :: Security
Provides-Extra: dev

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

txtorcon-18.1.0.tar.gz (307.4 kB view hashes)

Uploaded Source

Built Distribution

txtorcon-18.1.0-py2.py3-none-any.whl (337.2 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page