manhole

manhole-cli [-t seconds] [-1 | -2 | -s signal] pid

manhole is a Python library that opens a Unix domain socket (by default /tmp/manhole-pid) in a running process and serves an interactive Python REPL on it, with stack traces of all threads printed on connect. It is used to inspect live applications, including those using gevent or eventlet, without restarting them.The application enables it by calling manhole.install() (or by setting the PYTHONMANHOLE environment variable), optionally with oneshot_on or activate_on set to a signal so the socket is only created on demand. The manhole-cli command connects to that socket; tools like socat or nc -U can be used as well.

PID

Process ID, or a socket path of the form /tmp/manhole-pid.

Connection timeout (default 1 second).

Send SIGUSR1 to the process before connecting.

Send SIGUSR2 to the process before connecting.

Send the given signal (name or number) to the process before connecting.

Display help information.

The target process must have the manhole library installed and enabled; manhole-cli cannot inject it into an arbitrary process. Anyone who can connect gets full code execution in the process: only root or the same effective user may connect (checked via SO_PEERCRED), but it should still be used carefully in production. Unix-only.

python-manhole was written by Ionel Cristian Mărieș and first released on PyPI in 2013. The client command is installed as manhole-cli, not manhole.

py-spy(1), gdb(1), python(1), socat(1)

Source code · Documentation