manhole

What it is and what it does

Manhole is a debugging tool that runs inside your Python process and listens on a Unix domain socket. When you connect to that socket, it verifies your credentials (same user or root), redirects your standard streams, dumps stacktraces for all threads, and drops you into an interactive Python REPL where you can inspect and modify the running process. It's designed for production debugging—you can activate it on demand via a signal, run it in a background thread, or trigger it from a signal handler, and it handles forking, gevent, and eventlet with appropriate configuration.

The package has no runtime dependencies and installs as a pure Python wheel. It supports Python 3.8 through 3.12 on CPython and PyPy. Maintenance is dormant but the codebase is stable; the last release fixed a Python 3.11 buffering issue and cleaned up Python 2 remnants.

Use it for:

• Attach a live REPL to a running production service to inspect state or execute commands without stopping it.
• Dump stacktraces from all threads in a hung or slow process to diagnose deadlocks or performance issues.
• Trigger debugging on demand by sending a signal (e.g., SIGUSR1) to activate the manhole listener.
• Debug forking applications (e.g., uWSGI workers) where the manhole reinstalls itself after fork.
• Inspect and modify application state in gevent or eventlet async frameworks with oneshot or non-threaded modes.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Manhole installs an in-process debugging service that listens on a Unix domain socket, allowing you to connect and inspect thread stacktraces or drop into an interactive Python shell within a running process.

Yes, if you need in-process debugging on Unix/Linux production systems. The package is stable, has no dependencies, and solves a real problem—live inspection without stopping the process. The dormant maintenance is acceptable for a mature tool with a narrow, well-defined scope. Not suitable for Windows or when you cannot use Unix domain sockets.

Install

manhole on PyPI

pip install manhole

uv add manhole

poetry add manhole

Installing manhole

Before you install

Low friction to install—pure Python wheel with no runtime dependencies. Maintenance is dormant (771 days since last release), though the repository is not archived and the package is marked Production/Stable. Last commit was 2024-07-04.

License in practice

BSD-2-Clause is permissive; you may use, modify, and distribute this package with minimal restrictions, provided you retain the license notice.

Quickstart

import manhole
manhole.install()

# Then connect via: socat - UNIX-CONNECT:/tmp/manhole-<pid>

Requires Unix/POSIX OS (Linux, OS X); not available on Windows. Requires Python 3.8 or later.

Verify before relying

• Whether the 771-day dormancy affects compatibility with Python 3.12 or newer in practice beyond the stated support.
• Whether the known deadlock issue with file-handle verbose_destination on Python 3.4+ still manifests on current Python versions.

Package facts

Evidence: manhole-1.8.1-py3-none-any.whl

Keywords: debugging, manhole, thread, socket, unix domain socket

Tags

More Utilities packages