Simple Python interface for HTTP(s) requests over Tor
Clone or download
erdiaker Merge pull request #3 from Surkal/master
Fix https proxy typo.
Latest commit 8c1b5d0 Oct 11, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
.gitignore Update readme. Add .gitignore. Aug 18, 2016 Clarify readme. Sep 12, 2017
setup.cfg Initial commit. Aug 17, 2016 Initial commit. Aug 17, 2016 fix https proxy Oct 11, 2018


A simple Python interface for HTTP(s) requests over Tor.

from torrequest import TorRequest

with TorRequest() as tr:
  response = tr.get('')
  print(response.text)  # not your IP address

It's basically a wrapper around Stem and Requests libraries.


You need Tor. It's available via Homebrew.

brew install tor

After installation, you may want to configure Tor by creating a .torrc file in your $HOME directory. More information is available on Tor documentation.


After installing dependencies, you can install torrequest via PyPI:

pip install torrequest


from torrequest import TorRequest

# Choose a proxy port, a control port, and a password. 
# Defaults are 9050, 9051, and None respectively. 
# If there is already a Tor process listening the specified 
# ports, TorRequest will use that one. 
# Otherwise, it will create a new Tor process, 
# and terminate it at the end.
with TorRequest(proxy_port=9050, ctrl_port=9051, password=None) as tr:

  # Specify HTTP verb and url.
  resp = tr.get('')

  # Send data. Use basic authentication.
  resp ='', 
    data={'foo': 'bar'}, auth=('user', 'pass'))'

  # Change your Tor circuit,
  # and likely your observed IP address.

  # TorRequest object also exposes the underlying Stem controller 
  # and Requests session objects for more flexibility.

  print(type(tr.ctrl))            # a stem.control.Controller object
  tr.ctrl.signal('CLEARDNSCACHE') # see Stem docs for the full API

  print(type(tr.session))         # a requests.Session object
  c = cookielib.CookieJar()
  tr.session.cookies.update(c)    # see Requests docs for the full API