Skip to content
Fault handler for Python: display the Python backtrace on SIGSEGV, SIGFPE, SIGABRT, SIGBUS and SIGILL signals
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
doc set 3.1 release date in the doc Feb 11, 2019
.gitignore ignore more generated files Mar 3, 2015
.travis.yml Use tox-travis for painless py26 testing Nov 19, 2017
AUTHORS Added Giuseppe Corbelli as contributor for thread name printout on Linux May 29, 2015
COPYING Revert "Remove faulthandler.pth: try to fix Travis/Windows" Mar 22, 2017
README.rst Add the "No Maintenance Intended" badge Mar 9, 2018
TODO sync with cpython; set version to 2.0 Apr 8, 2011
faulthandler.embed Generate the .pth file from something readable. Run ` genpth`… Apr 19, 2015
faulthandler.pth Revert "Remove faulthandler.pth: try to fix Travis/Windows" Mar 22, 2017
releaser.conf becomes Nov 17, 2017 Accept "python2.7" thread name in tests Feb 19, 2018
tox.ini tox: run tests in verbose mode Mar 22, 2017
traceback.c Backport of Windows exception handler from Python 3.5 + adjust tests … Aug 27, 2017


Fault handler

Latest release on the Python Cheeseshop (PyPI) Build status of faulthandler on Travis CI No Maintenance Intended

Fault handler for SIGSEGV, SIGFPE, SIGABRT, SIGBUS and SIGILL signals: display the Python traceback and restore the previous handler. Allocate an alternate stack for this handler, if sigaltstack() is available, to be able to allocate memory on the stack, even on stack overflow (not available on Windows).

Import the module and call faulthandler.enable() to enable the fault handler.

Alternatively you can set the PYTHONFAULTHANDLER environment variable to a non-empty value.

The fault handler is called on catastrophic cases and so it can only use signal-safe functions (eg. it doesn't allocate memory on the heap). That's why the traceback is limited: it only supports ASCII encoding (use the backslashreplace error handler for non-ASCII characters) and limits each string to 100 characters, doesn't print the source code in the traceback (only the filename, the function name and the line number), is limited to 100 frames and 100 threads.

By default, the Python traceback is written to the standard error stream. Start your graphical applications in a terminal and run your server in foreground to see the traceback, or pass a file to faulthandler.enable().

faulthandler is implemented in C using signal handlers to be able to dump a traceback on a crash or when Python is blocked (eg. deadlock).

This module is the backport for CPython 2.7. faulthandler is part of CPython standard library since CPython 3.3: faulthandler. For PyPy, faulthandler is builtin since PyPy 5.5: use pypy -X faulthandler.


You can’t perform that action at this time.