Debug Python Crash Logs with faulthandler

Ever had your Python script crash and leave you staring at a blank terminal? That sinking feeling when you know something went wrong, but there's no traceback, no error message—just silence. It's frustrating, especially when you're working on something important at PythonSkillset.

The good news is that Python has a built-in module called faulthandler that can save you hours of debugging. It's like having a black box recorder for your Python programs.

What faulthandler does

When your Python program crashes due to a segfault, memory corruption, or similar low-level errors, the normal Python traceback doesn't get printed. faulthandler captures these crashes and gives you a stack trace showing exactly where the crash happened.

Think of it as the difference between your car engine seizing up with a check engine light versus just dying without any warning. faulthandler is that check engine light.

Getting started

You need to enable faulthandler early in your script. The best practice is to add it at the very beginning:

import faulthandler
faulthandler.enable()

That's it. Now if your program crashes, you'll see a stack trace printed to stderr showing the call stack at the moment of the crash.

Real-world example

Let's say you're working on a video processing script for PythonSkillset's guide on image manipulation. You've got a loop that processes thousands of frames, and occasionally—maybe after hours of processing—the script dies without any error message.

Without faulthandler, you'd have to add print statements everywhere, try to reproduce the crash, and hope you catch it. With faulthandler, when the crash happens, you'll see:

Fatal Python error: Segmentation fault

Current thread 0x00007f8c8bfff700 (most recent call first):
  File "/path/to/your_script.py", line 42 in process_frame
  File "/path/to/your_script.py", line 78 in main
  File "/path/to/your_script.py", line 92 in <module>

Now you know exactly which function caused the problem. In this case, it's the process_frame function on line 42. You can inspect that code and likely find a memory bug or an incompatible library.

Where crashes usually happen

Segfaults in Python almost always come from C extensions. Common culprits:

• NumPy operations that create very large arrays
• Pandas when working with huge DataFrames
• OpenCV or other image/video processing libraries
• Cython compiled code
• Ctypes or CFFI bindings to native libraries

The crashes are rarely in pure Python code. Python's memory management is too robust for segfaults in its own code.

Saving crash logs

You can also save faulthandler output to a file, which is useful for server applications or when you can't watch the terminal:

import faulthandler

with open('crash.log', 'w') as f:
    faulthandler.enable(file=f)

Or you can dump the traceback on demand if you catch a signal:

import faulthandler
import signal

faulthandler.register(signal.SIGUSR1)

Then you can send a SIGUSR1 signal to your process (using kill -SIGUSR1 <pid>) to get a stack trace of all running threads without killing the process.

When to use it

Add faulthandler to any script that:

• Uses C extensions
• Processes large amounts of data
• Runs for long periods (hours or days)
• Runs in production environments
• Handles user-supplied files or data

I always add it to my PythonSkillset scripts during development and leave it in for production. It adds virtually no overhead and can save you from chasing bugs for days.

The gotcha

The one thing to watch out for: faulthandler can sometimes print the stack trace even when Python handles the error gracefully. For example, if you catch a KeyboardInterrupt, faulthandler might still show a traceback. But that's a minor nuisance compared to chasing silent crashes.

Next steps

If you're dealing with a crash that faulthandler catches, the next step is usually to check if you're passing the right data types to C functions, or if you've got a memory leak from not cleaning up resources.

For deep debugging, you might need gdb or Valgrind, but faulthandler gives you 80% of the answers with almost no effort. It's one of those tools that every Python developer should know about, but most don't discover until they've wasted hours debugging a segfault the hard way.