`faulthandler`

The Python faulthandler module provides tools for diagnosing Python interpreter crashes and fatal signals. When a catastrophic signal such as SIGSEGV or SIGABRT occurs, the fault handler prints a traceback to sys.stderr instead of leaving only an OS-level crash message.

It is implemented in C so it remains functional even when the interpreter is in a corrupted state. Enable it for an entire process with the -X faulthandler flag, the PYTHONFAULTHANDLER environment variable, or a direct API call:

>>> import faulthandler

>>> faulthandler.enable()
>>> faulthandler.is_enabled()
True

Key Features

Dumps Python tracebacks on fatal signals: SIGSEGV, SIGFPE, SIGABRT, SIGBUS, and SIGILL
Dumps tracebacks for all running threads or only the current thread
Schedules a traceback dump after a timeout to detect hung or deadlocked processes
Registers user-defined signals to trigger an on-demand traceback dump (Unix only)
Writes output to any writable file object or file descriptor

Frequently Used Classes and Functions

Object	Type	Description
`faulthandler.enable()`	Function	Installs fault handlers for fatal signals
`faulthandler.disable()`	Function	Uninstalls the fault handlers installed by `enable()`
`faulthandler.is_enabled()`	Function	Returns `True` if the fault handler is currently enabled
`faulthandler.dump_traceback()`	Function	Dumps the traceback of all threads to a file immediately
`faulthandler.dump_traceback_later()`	Function	Schedules a traceback dump after a given number of seconds
`faulthandler.cancel_dump_traceback_later()`	Function	Cancels a pending scheduled traceback dump
`faulthandler.register()`	Function	Registers a user signal to trigger a traceback dump (Unix only)

Examples

Enabling the fault handler from the command line or via an environment variable:

$ python -X faulthandler my_script.py

$ PYTHONFAULTHANDLER=1 python my_script.py

Redirecting crash output to a log file instead of sys.stderr:

>>> import faulthandler

>>> log = open("crash.log", "w")
>>> faulthandler.enable(file=log)
>>> faulthandler.is_enabled()
True

Scheduling a traceback dump if a block of code doesn’t finish within a timeout:

>>> import faulthandler

>>> faulthandler.dump_traceback_later(30.0)
>>> # Run potentially slow code here...
>>> faulthandler.cancel_dump_traceback_later()

Common Use Cases

The most common tasks for faulthandler include:

Diagnosing segmentation faults in C extension modules
Detecting deadlocked threads by triggering a timeout-based traceback dump
Logging crash information to a file in long-running production services
Capturing tracebacks on demand by registering a SIGUSR1 handler (Unix)
Enabling always-on crash reporting with PYTHONFAULTHANDLER=1

Real-World Example

Imagine a program that processes tasks one after another. If a task gets stuck, the program hangs with no indication of what went wrong. You can use dump_traceback_later() to set a time limit. If a task doesn’t finish in time, faulthandler writes a traceback to a log file and exits:

import faulthandler
import random
import time

LOG = open("worker_crash.log", "w")
faulthandler.enable(file=LOG)

TASK_TIMEOUT = 5.0

def run_task(task_id):
    faulthandler.dump_traceback_later(
        TASK_TIMEOUT, exit=True, file=LOG
    )
    try:
        print(f"Starting task {task_id}")
        time.sleep(random.uniform(1, 8))
        print(f"Task {task_id} done.")
    finally:
        faulthandler.cancel_dump_traceback_later()

for i in range(4):
    run_task(i)

LOG.close()

If every task finishes within five seconds, the program runs normally. But if a task exceeds the timeout, faulthandler dumps a traceback to the log file and stops the program:

$ python worker.py
Starting task 0
Task 0 done.
Starting task 1
Task 1 done.
Starting task 2

$ cat worker_crash.log
Timeout (0:00:05)!
Thread 0x00007f8b8a3f0740 (most recent call first):
  File "worker.py", line 16 in run_task
  File "worker.py", line 22 in <module>

Tasks 0 and 1 finished in time, but task 2 exceeded the five-second limit. The log shows exactly which line the program was on when it got stuck.

Tutorial

Understanding the Python Traceback

In this step-by-step tutorial, you'll learn how to read and understand the information you can get from a Python traceback. You'll walk through several examples of tracebacks and see some of the most common tracebacks in Python.

basics python

For additional information on related topics, take a look at the following resources: