stem examples
Go to file 9c6594c301 update
2024-02-21 08:03:10 +00:00
docs second 2024-01-14 14:28:53 +00:00
src/stem_examples update 2024-02-21 08:03:10 +00:00
.gitignore tests 2024-01-16 18:10:43 +00:00
Makefile update 2024-02-21 08:03:10 +00:00
pyproject.toml update 2024-02-21 08:03:10 +00:00 update 2024-01-17 20:35:20 +00:00
setup.cfg update 2024-02-21 08:03:10 +00:00
stem_examples.txt update 2024-02-05 14:26:19 +00:00


Examples of using the Python stem library to query the state of a running tor.

You can set TOR_CONTROLLER_PASSWORD in the environment if your tor control port requires a password.

  • check_digests
  • compare_flags
  • exit_used
  • introduction_points
  • list_circuits
  • mappaddress
  • outdated_relays
  • relay_connections
  • tor_bootstrap_check


Checking Descriptor Digests

Tor relay information is provided by multiple documents. Signed descriptors transitively validate others by inclusion of their digest. For example, our consensus references server descriptor digest, and server descriptors in turn cite extrainfo digests.

Stem can calculate digests from server, extrainfo, microdescriptor, and consensus documents. For instance, to validate an extrainfo descriptor...

compare_flags Comparing Directory Authority Flags

Compares the votes of two directory authorities, in this case moria1 and maatuska, with a special interest in the 'Running' flag.

connection_resolution Connection Resolution

Connection information is a useful tool for learning more about network applications like Tor. Our stem.util.connection.get_connections() function provides an easy method for accessing this information.

exit_used Exit Used

Determine The Exit You're Using

introduction_points Introduction Points

This script tests if you can reach a hidden service, passed as an onion address as an argument. If no argument is given, 3 common onion sites are tested: Facebook, DuckDuckGo, and .

list_circuits List Circuits

Tor creates new circuits and tears down old ones on your behalf, so how can you get information about circuits Tor currently has available?


Mappaddress queries the socks proxy with an onion address and returns the IP address that it will use for it. the address will be in the block specified by the VirtualAddrNetworkIPv4 setting of the torrc, e.g.


outdated_relays List Outdated Relays

Time marches on. Tor makes new releases, and at some point needs to drop support for old ones. Below is the script we used on ticket 9476 to reach out to relay operators that needed to upgrade.

relay_connections Connection Summary

The following provides a summary of your relay's inbound and outbound connections.

To use this you must set DisableDebuggerAttachment 0 in your torrc. Otherwise connection information will be unavailable.

Download Tor Descriptors

Tor relays provide a mirror for the tor relay descriptors it has cached. These are available from its ORPort using Tor's wire protocol, and optionally with http as well from a DirPort.

Votes by Bandwidth Authorities

Tor takes into account a relay's throughput when picking a route through the Tor network for its circuits. That is to say large, fast relays receive more traffic than small ones since they can better service the load.

To determine a relay's throughput special authorities, called bandwidth authorities, take periodic measurements using them. The lifecycle of new Tor relays is a bit more complicated than that, butthat's the general idea.

Bandwidth authorities include their measurements in their votes. The following gets their current votes then prints how many relays it had a measurement for.


A script by to check what percentage of boostrapping tor is at.