stem

library1.8.2pypypi✓ verified 84d ago

Stem is a Python controller library that provides a high-level API for interacting with the Tor daemon. It allows applications to query Tor's status, manage circuits and streams, and retrieve information about Tor relays. The current stable version is 1.8.2, with releases occurring as needed for bug fixes and minor enhancements.

communication http-networking auth-security

pip install stem

package ↗homepage ↗

INSTALL

IMPORT

SIG · STEM

stem

communicationpythonv1.8.2

Install

2.9s avg

Import

202ms

Disk

20MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.8.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.215s · 21.9MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 2.9s · import 0.190s · 22MB

20MB installed

● package 20MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Controller

✓ from stem.control import Controller

✗ from stem import Controller

Controller is part of the 'control' submodule.

launch_tor_with_config

✓ from stem.process import launch_tor_with_config

✗ from stem import launch_tor_with_config

Function to launch Tor is in the 'process' submodule.

SocketClosed

✓ from stem import SocketClosed

Common exception for connection issues.

This example connects to a running Tor daemon's control port (typically 9051) and authenticates using either an environment variable for a password or via Tor's default cookie-based authentication. It then prints the Tor version and the number of active circuits.

import stem.control import os # Default Tor control port is 9051. Authenticate with password or cookie. try: with stem.control.Controller.from_port(port=9051) as controller: # Attempt authentication. If TOR_CONTROL_PASSWORD env var is set, use it. # Otherwise, authenticate() without arguments tries cookie authentication. auth_password = os.environ.get('TOR_CONTROL_PASSWORD', '') if auth_password: controller.authenticate(password=auth_password) else: controller.authenticate() # Attempts cookie authentication by default print("Successfully connected to Tor controller!") print(f"Tor version: {controller.get_version()}") # Example: Get all active circuits circuits = controller.get_circuits() print(f"Number of active Tor circuits: {len(circuits)}") except stem.SocketClosed: print("Error: Could not connect to Tor's control port. Is Tor running?") print("Check your Tor configuration (torrc) for ControlPort and authentication settings.") except Exception as e: print(f"An unexpected error occurred: {e}")

stem --version

Debug

Known issues

gotchaStem requires a running Tor daemon to connect to its control port. If Tor is not running or its control port (e.g., 9051) is not accessible, you will get connection errors like `SocketClosed`.

fix

Ensure Tor is installed and running. Check your `torrc` file for `ControlPort` and `SocksPort` settings. You can optionally use `stem.process.launch_tor_with_config` to start a Tor process.

affects: All versions

gotchaAuthentication failures are common, especially when Tor is configured with a `HashedControlPassword` or `CookieAuthentication` and stem can't find the correct credentials.

fix

Provide the correct `HashedControlPassword` to `controller.authenticate(password='your_password')` or ensure stem can access the Tor cookie file. If using default `CookieAuthentication`, `controller.authenticate()` without arguments should work if the cookie file is in its default location.

affects: All versions

gotchaThe `stem.process` module to launch Tor can be tricky. It requires the `tor` executable to be in your PATH or explicitly specified, and managing its lifecycle (starting, stopping, cleaning up) is crucial to avoid orphaned processes.

fix

Always use `with launch_tor_with_config(...) as tor_process:` or ensure `tor_process.kill()` is called in a `finally` block. Pass `tor_path='path/to/tor'` if not in PATH. Ensure `init_msg_handler` is used for proper startup feedback.

affects: All versions

Errors

Common errors & fixes

stem.SocketClosed: [Errno 111] Connection refused

Tor's control port is not listening or is blocked, or Tor is not running.

fix

Verify that Tor is running and that its `ControlPort` is configured and accessible (e.g., `ControlPort 9051`). Check firewall rules. If launching Tor with `stem.process`, ensure `tor_path` is correct and Tor starts successfully.

stem.ProtocolError: Keyword authentication failed

Incorrect password provided for Tor's control port.

fix

Provide the correct `HashedControlPassword` to `controller.authenticate(password='your_password')`. Double-check your `torrc` file for the password setting.

stem.SocketClosed: connection was closed (cookie authentication did not provide a response)

Tor is configured for cookie authentication, but stem cannot find or read the authentication cookie file.

fix

Ensure `CookieAuthentication 1` is set in `torrc` and the `CookieAuthFile` is in a default or accessible location. If manually specifying, pass `controller.authenticate(private_key='/path/to/control_auth_cookie')`.

Upgrade

Version history

1.8.2latest on PyPI · released Jun 6, 2023

Audit

Dependencies

No dependency data recorded yet.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://pypi.org/project/stem/ ↗

homepagehttps://stem.torproject.org/ ↗