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.
pip install manholeVerified import paths — ran on the pinned version, not inferred.
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`.
Upgrade to Python >=3.8 or pin `manhole` to a compatible version like `manhole<1.6.0`.
Upgrade to `manhole` v1.7.0 or newer to benefit from the memory leak and double-close bug fixes.
Upgrade to `manhole` v1.6.0 or newer to ensure correct handling when `socket.setdefaulttimeout()` is in use.
Upgrade to `manhole` v1.7.0 or newer, or ensure socket paths provided to `manhole-cli` are `/tmp`-prefixed for older versions.
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.
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.
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.
Install the package using pip: `pip install manhole` or ensure your virtual environment is activated if you installed it there.
Ensure `manhole.install()` has been called in the target Python application to start the manhole server. Verify the `socket_path` is correct and that the process running `manhole-cli` has permission to access it. Check for stray socket files in `/tmp` and remove them if the application crashed. For remote connections, ensure the path and permissions are correctly set.
Ensure the user running the Python application has write permissions to the directory where the socket file is created (e.g., `/tmp`). Alternatively, specify a `socket_path` in `manhole.install(socket_path='/path/to/writable/dir/mysocket')` to a directory where the user has appropriate permissions.
For uWSGI, follow the specific integration instructions in the `manhole` documentation to use uWSGI signals and file monitoring, as uWSGI overrides standard signal handling. Ensure the `stack_dump_file` path is writable by the uWSGI worker process.
If you intend to reinstall or allow multiple installations, call `manhole.install(strict=False)`. If multiple installations are unintentional, debug your application startup to ensure `manhole.install()` is only called once.