{"id":4099,"library":"manhole","title":"Manhole - In-process Python Debugging Shell","description":"Manhole is an in-process Python service that accepts Unix domain socket connections to provide stack traces for all threads and an interactive Python prompt. It can operate as a daemon thread or a signal handler. It is inspired by Twisted's manhole and focuses on simplicity with no external dependencies. The current version is 1.8.1, and releases appear to be on a somewhat irregular, feature-driven cadence.","status":"active","version":"1.8.1","language":"en","source_language":"en","source_url":"https://github.com/ionelmc/python-manhole","tags":["debugging","repl","interactive shell","unix socket","introspection","diagnostics"],"install":[{"cmd":"pip install manhole","lang":"bash","label":"Install Manhole"}],"dependencies":[{"reason":"Minimum required Python version for the library.","package":"python","version":">=3.8","optional":false}],"imports":[{"note":"The primary way to activate the manhole in your application.","symbol":"install","correct":"import manhole\nmanhole.install()"},{"note":"One of the provided connection handlers, offering a full REPL experience.","symbol":"handle_connection_repl","correct":"from manhole import handle_connection_repl"},{"note":"An alternative connection handler, providing a simpler 'exec' environment without full REPL features.","symbol":"handle_connection_exec","correct":"from manhole import handle_connection_exec"}],"quickstart":{"code":"import manhole\nimport time\nimport os\nimport sys\n\ndef main():\n    print(f\"Manhole will listen on /tmp/manhole-{os.getpid()}\\n\")\n    manhole.install(sigmask=[\"USR1\"], verbose=True) # Install manhole with default settings\n    print(\"Manhole installed. Waiting for connection...\")\n    \n    # Simulate a running application\n    i = 0\n    while True:\n        print(f\"App running... {i}\")\n        time.sleep(2)\n        i += 1\n        if i == 5: # Optionally demonstrate manual activation/deactivation\n            print(\"Sending USR1 to self to potentially activate/deactivate manhole if configured as 'activate_on'\")\n            try:\n                os.kill(os.getpid(), 10) # SIGUSR1\n            except AttributeError:\n                print(\"SIGUSR1 not available on this OS, skipping manual signal.\")\n\n\nif __name__ == '__main__':\n    import subprocess\n    # Start the application with manhole installed\n    app_process = subprocess.Popen([sys.executable, __file__])\n    time.sleep(3)\n    \n    # Connect to the manhole using manhole-cli\n    print(f\"\\nConnecting to manhole-cli for PID: {app_process.pid}...\")\n    try:\n        # The `manhole-cli` attempts to connect to /tmp/manhole-<PID>\n        # Note: 'socat readline' provides a better interactive experience.\n        # 'manhole-cli' is simpler for demonstration.\n        subprocess.run(['manhole-cli', str(app_process.pid)], check=True)\n    except FileNotFoundError:\n        print(\"manhole-cli not found. Please ensure it's installed and in your PATH.\")\n    except subprocess.CalledProcessError as e:\n        print(f\"manhole-cli failed: {e}\")\n    finally:\n        app_process.terminate()\n        app_process.wait()\n        print(\"\\nApplication terminated.\")\n","lang":"python","description":"This quickstart demonstrates how to install `manhole` in a Python application and then connect to it using the `manhole-cli` tool. The application will print a message indicating the socket path, run in the background, and then `manhole-cli` will be used to establish an interactive session. Inside the manhole, you can inspect variables or execute code. For a richer interactive experience (history, editing), `socat readline unix-connect:/tmp/manhole-PID` is recommended instead of `manhole-cli`."},"warnings":[{"fix":"Upgrade to Python >=3.8 or pin `manhole` to a compatible version like `manhole<1.6.0`.","message":"Support for Python 2.6, 3.3, and 3.4 was dropped in v1.6.0. Applications running on these older Python versions will require an older `manhole` release (e.g., <1.6.0).","severity":"breaking","affected_versions":"<1.6.0"},{"fix":"Upgrade to `manhole` v1.7.0 or newer to benefit from the memory leak and double-close bug fixes.","message":"Previous versions (before v1.7.0) had a memory leak due to `sys.last_type`, `sys.last_value`, and `sys.last_traceback` not being cleared properly, and could also suffer from double-close bugs in stream handling.","severity":"gotcha","affected_versions":"<1.7.0"},{"fix":"Upgrade to `manhole` v1.6.0 or newer to ensure correct handling when `socket.setdefaulttimeout()` is in use.","message":"When `socket.setdefaulttimeout()` is used in your application, older `manhole` versions (before v1.6.0) might exhibit unexpected behavior. This was fixed in v1.6.0.","severity":"gotcha","affected_versions":"<1.6.0"},{"fix":"Upgrade to `manhole` v1.7.0 or newer, or ensure socket paths provided to `manhole-cli` are `/tmp`-prefixed for older versions.","message":"`manhole-cli` in versions prior to v1.7.0 was more strict about PID argument parsing, primarily expecting paths prefixed with `/tmp`. This was loosened in v1.7.0 to allow paths with any prefix.","severity":"gotcha","affected_versions":"<1.7.0"},{"fix":"If re-installation or multiple calls are intended, set `strict=False` in `manhole.install(strict=False)` or use the `reinstall_delay` option. An existing manhole can also be uninstalled before reinstalling.","message":"By default, calling `manhole.install()` multiple times will raise an `AlreadyInstalled` exception. This is part of 'strict' mode.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Refer to the `manhole` documentation's 'Using Manhole with uWSGI' section for specific setup instructions, often involving `oneshot_on` or `activate_on` options with uWSGI signals.","message":"Integrating `manhole` with uWSGI requires special configuration because uWSGI overrides signal handling. The recommended approach involves using uWSGI's internal signals or a file-based PID mechanism.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be aware of the `PYTHONMANHOLE` environment variable if your application exhibits unexpected manhole behavior. Ensure it's not set unintentionally or use it deliberately for deployment scenarios.","message":"Manhole can also be installed via the `PYTHONMANHOLE` environment variable. If set, Manhole might be automatically activated, potentially conflicting with explicit `manhole.install()` calls or altering expected behavior.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}