{"id":10267,"library":"stem","title":"Stem - Tor Controller Library","description":"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.","status":"active","version":"1.8.2","language":"en","source_language":"en","source_url":"https://gitweb.torproject.org/stem.git","tags":["tor","network","anonymity","proxy","controller"],"install":[{"cmd":"pip install stem","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"Controller is part of the 'control' submodule.","wrong":"from stem import Controller","symbol":"Controller","correct":"from stem.control import Controller"},{"note":"Function to launch Tor is in the 'process' submodule.","wrong":"from stem import launch_tor_with_config","symbol":"launch_tor_with_config","correct":"from stem.process import launch_tor_with_config"},{"note":"Common exception for connection issues.","symbol":"SocketClosed","correct":"from stem import SocketClosed"}],"quickstart":{"code":"import stem.control\nimport os\n\n# Default Tor control port is 9051. Authenticate with password or cookie.\ntry:\n    with stem.control.Controller.from_port(port=9051) as controller:\n        # Attempt authentication. If TOR_CONTROL_PASSWORD env var is set, use it.\n        # Otherwise, authenticate() without arguments tries cookie authentication.\n        auth_password = os.environ.get('TOR_CONTROL_PASSWORD', '')\n        if auth_password:\n            controller.authenticate(password=auth_password)\n        else:\n            controller.authenticate() # Attempts cookie authentication by default\n\n        print(\"Successfully connected to Tor controller!\")\n        print(f\"Tor version: {controller.get_version()}\")\n        \n        # Example: Get all active circuits\n        circuits = controller.get_circuits()\n        print(f\"Number of active Tor circuits: {len(circuits)}\")\n\nexcept stem.SocketClosed:\n    print(\"Error: Could not connect to Tor's control port. Is Tor running?\")\n    print(\"Check your Tor configuration (torrc) for ControlPort and authentication settings.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"Stem 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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Authentication failures are common, especially when Tor is configured with a `HashedControlPassword` or `CookieAuthentication` and stem can't find the correct credentials.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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.","cause":"Tor's control port is not listening or is blocked, or Tor is not running.","error":"stem.SocketClosed: [Errno 111] Connection refused"},{"fix":"Provide the correct `HashedControlPassword` to `controller.authenticate(password='your_password')`. Double-check your `torrc` file for the password setting.","cause":"Incorrect password provided for Tor's control port.","error":"stem.ProtocolError: Keyword authentication failed"},{"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')`.","cause":"Tor is configured for cookie authentication, but stem cannot find or read the authentication cookie file.","error":"stem.SocketClosed: connection was closed (cookie authentication did not provide a response)"}]}