Skip to main content

Inspection manhole for python applications. Connection is done via unix domain sockets.

Project description


Documentation Status


Travis-CI Build Status AppVeyor Build Status
Coverage Status Coverage Status Code Quality Status Scrutinizer Status


PyPI Package latest release PyPI Package monthly downloads

Manhole is in-process service that will accept unix domain socket connections and present the stacktraces for all threads and an interactive prompt. It can either work as a python daemon thread waiting for connections at all times or a signal handler (stopping your application and waiting for a connection).

Access to the socket is restricted to the application’s effective user id or root.

This is just like Twisted’s manhole. It’s simpler (no dependencies), it only runs on Unix domain sockets (in contrast to Twisted’s manhole which can run on telnet or ssh) and it integrates well with various types of applications.



Install it:

pip install manhole

You can put this in your django settings, wsgi app file, some module that’s always imported early etc:

import manhole
manhole.install() # this will start the daemon thread

# and now you start your app, eg: server.serve_forever()

Now in a shell you can do either of these:

netcat -U /tmp/manhole-1234
socat - unix-connect:/tmp/manhole-1234
socat readline unix-connect:/tmp/manhole-1234

Socat with readline is best (history, editing etc).

Sample output:

$ nc -U /tmp/manhole-1234

Python 2.7.3 (default, Apr 10 2013, 06:20:15)
[GCC 4.6.3] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> dir()
['__builtins__', 'dump_stacktraces', 'os', 'socket', 'sys', 'traceback']
>>> print 'foobar'

Alternative client

There’s a new experimental manhole bin since 1.1.0, that emulates socat:

usage: manhole [-h] [-t TIMEOUT] [-1 | -2] PID

Connect to a manhole.

positional arguments:
  PID                   A numerical process id, or a path in the form:

optional arguments:
  -h, --help            show this help message and exit
  -t TIMEOUT, --timeout TIMEOUT
                        Timeout to use. Default: 1 seconds.
  -1, -USR1             Send USR1 (10) to the process before connecting.
  -2, -USR2             Send USR2 (12) to the process before connecting.


  • Uses unix domain sockets, only root or same effective user can connect.

  • Can run the connection in a thread or in a signal handler (see oneshot_on option).

  • Can start the thread listening for connections from a signal handler (see activate_on option)

  • Compatible with apps that fork, reinstalls the Manhole thread after fork - had to monkeypatch os.fork/os.forkpty for this.

  • Compatible with gevent and eventlet with some limitations - you need to either:

    • Use oneshot_on, or

    • Disable thread monkeypatching (eg: gevent.monkey.patch_all(thread=False), eventlet.monkey_patch(thread=False)

  • The thread is compatible with apps that use signalfd (will mask all signals for the Manhole threads).


  • verbose - Set it to False to squelch the logging.

  • verbose_destination - Destination for verbose messages. Set it to a file descriptor or handle. Default is unbuffered stderr (stderr 2 file descriptor).

  • patch_fork - Set it to False if you don’t want your os.fork and os.forkpy monkeypatched

  • activate_on - Set to "USR1", "USR2" or some other signal name, or a number if you want the Manhole thread to start when this signal is sent. This is desireable in case you don’t want the thread active all the time.

  • oneshot_on - Set to "USR1", "USR2" or some other signal name, or a number if you want the Manhole to listen for connection in the signal handler. This is desireable in case you don’t want threads at all.

  • sigmask - Will set the signal mask to the given list (using signalfd.sigprocmask). No action is done if signalfd is not importable. NOTE: This is done so that the Manhole thread doesn’t steal any signals; Normally that is fine cause Python will force all the signal handling to be run in the main thread but signalfd doesn’t.

  • socket_path - Use a specifc path for the unix domain socket (instead of /tmp/manhole-<pid>). This disables patch_fork as children cannot resuse the same path.

  • reinstall_delay - Delay the unix domain socket creation reinstall_delay seconds. This alleviates cleanup failures when using fork+exec patterns.

  • locals - Names to add to manhole interactive shell locals.

  • daemon_connection - The connection thread is daemonic (dies on app exit). Default: False.

  • redirect_stderr - Redirect output from stderr to manhole console. Default: True.

  • strict - If True then AlreadyInstalled will be raised when attempting to install manhole twice. Default: True.

Environment variable installation

Manhole can be installed via the PYTHONMANHOLE environment varialbe.



Is equivalent to having this in

import manhole manhole.install()

Any extra text in the environment variable is passed to manhole.install(). Example:

PYTHONMANHOLE='onshot_on="USR2"' python

What happens when you actually connect to the socket

  1. Credentials are checked (if it’s same user or root)

  2. sys.__std*__/sys.std* are be redirected to the UDS

  3. Stacktraces for each thread are written to the UDS

  4. REPL is started so you can fiddle with the process

Known issues

  • Using threads and file handle (not raw file descriptor) verbose_destination can cause deadlocks. See bug reports: PyPy and Python 3.4.

SIGTERM and socket cleanup

By default Python doesn’t call the atexit callbacks with the default SIGTERM handling. This makes manhole leave stray socket files around. If this is undesirable you should install a custom SIGTERM handler so atexit is properly invoked.


import signal
import sys

def handle_sigterm(signo, frame):
    sys.exit(128 + signo)  # this will raise SystemExit and cause atexit to be called

signal.signal(signal.SIGTERM, handle_sigterm)



Linux, OS X


Python 2.6, 2.7, 3.2, 3.3, 3.4 or PyPy

Similar projects


1.2.0 (2015-07-06)

  • Changed manhole-cli:

    • Won’t spam the terminal with errors if socket file doesn’t exist.

    • Allowed sending any signal (new --signal argument).

    • Fixed some validation issues for the PID argument.

1.1.0 (2015-06-06)

  • Added support for installing the manhole via the PYTHONMANHOLE environment variable.

  • Added a strict install option. Set it to false to avoid getting the AlreadyInstalled exception.

  • Added a manhole-cli script that emulates socat readline unix-connect:/tmp/manhole-1234.

1.0.0 (2014-10-13)

  • Added socket_path install option (contributed by Nir Soffer).

  • Added reinstall_delay install option.

  • Added locals install option (contributed by Nir Soffer).

  • Added redirect_stderr install option (contributed by Nir Soffer).

  • Lots of internals cleanup (contributed by Nir Soffer).

0.6.2 (2014-04-28)

  • Fix OS X regression.

0.6.1 (2014-04-28)

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

manhole-1.2.0.tar.gz (34.7 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page