Python 3.3+Linux · macOSfaulthandlerfunction

faulthandler.register()

dump on signal

Makes a signal (such as SIGUSR1) dump the stack of all threads — a way to peek into a running program from outside. Linux and macOS.

Syntax

faulthandler.register(signum, file=sys.stderr, all_threads=True, chain=False)

The function does not exist on Windows. Typical use: register(signal.SIGUSR1) at startup, and when the service seems stuck run kill -USR1 <pid> in a terminal — the stack appears on stderr and the program keeps running. Fatal signals (SIGSEGV, SIGABRT…) cannot be registered this way — RuntimeError suggests enable() instead. chain=True also calls the previous signal handler.

Examples

import faulthandler, signal
with open('sig.txt', 'w') as f:
    faulthandler.register(signal.SIGUSR1, file=f, all_threads=False)
    signal.raise_signal(signal.SIGUSR1)
    faulthandler.unregister(signal.SIGUSR1)
print(open('sig.txt').read().splitlines()[0])  # → Stack (most recent call first):

import faulthandler, signal
try:
    faulthandler.register(signal.SIGSEGV)
except RuntimeError as e:
    print(e)  # → signal 11 cannot be registered, use enable() instead

See also

Common errors

Open in the full glossarydocs.python.orgReport an inaccuracy