Skip to main content
Help us improve Python packaging – donate today!

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

Project Description

Manhole is a python daemon thread that will accept unix domain socket connections and present the stacktraces for all threads and an interactive prompt.

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) and it only runs on Unix domain sockets (in contrast to Twisted’s manhole which can run on telnet or ssh).

Usage (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

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'


  • Uses unix domain sockets, only root or same effective user can connect.
  • Current implementation runs a daemon thread that waits for connection.
  • Compatible with apps that fork, reinstalls the Manhole thread after fork - had to monkeypatch os.fork/os.forkpty for this.


manhole.install(verbose=True, patch_fork=True, activate_on=None, sigmask=manhole.ALL_SIGNALS)

  • verbose - set it to False to squelch the stderr ouput
  • 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.
  • 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.

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


  • Be compatible with eventlet/stackless (provide alternative implementation without thread)
  • More configurable (chose what sys.__std*__/sys.std* to patch on connect time)


Not sure yet … maybe Python 2.6 and 2.7. Check Travis:

Build Status Coverage Status

Coverage is wrong, must be a bug in coveralls, it should be at least 80%-90% depending whether you count branches or not.

Similar projects

Release history Release notifications

History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


This version
History Node


History Node


History Node


History Node


History Node


History Node


History Node


Download files

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

Filename, size & hash SHA256 hash help File type Python version Upload date
manhole-0.3.1.tar.gz (10.1 kB) Copy SHA256 hash SHA256 Source None Jul 18, 2013

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page