`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

The enable() function takes three optional arguments: file sets where the dump goes, all_threads controls whether every thread is included, and c_stack (Python 3.14+) adds the C-level stack trace to the output.

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, although free-threaded builds with the GIL disabled always dump 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)
Dumps the C-level stack trace alongside the Python traceback on supported platforms (Python 3.14+)
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, plus the C stack when `c_stack=True` (Python 3.14+)
`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_c_stack()`	Function	Dumps the C stack trace of the current thread to a file (Python 3.14+)
`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:

Getting the Most Out of a Python Traceback (Course)
Building a Python C Extension Module (Tutorial)
An Intro to Threading in Python (Tutorial)
Logging in Python (Tutorial)
Python Debugging With Pdb (Tutorial)
Debugging in Python With pdb (Course)
Understanding the Python Traceback (Quiz)
Threading in Python (Course)
Python Threading (Quiz)
Logging Inside Python (Course)
Logging in Python (Quiz)
Python Debugging With Pdb (Quiz)

Have a question about this? Mentor AI can show you examples, compare related terms, and point you to tutorials.

By Leodanis Pozo Ramos • Updated Sept. 21, 2026

Python Standard Library Share Feedback

faulthandler