tblib: Traceback Serialization Library

3.2.2 · active · verified Sun Mar 29

tblib is a Python library that allows for the serialization of exceptions and tracebacks, enabling them to be pickled and unpickled across different processes. This is particularly useful for robust error handling in multiprocessing or distributed systems like Celery. It also provides methods to create tracebacks from strings or serialize them to and from dictionaries. The current version is 3.2.2, with releases occurring periodically, often for bug fixes and Python version support updates.

Warnings

breaking tblib v2.0.0 removed support for Python 2.7 and 3.6. Subsequent versions (v3.0.0 and v3.1.0) also dropped support for Python 3.7 and 3.8 respectively, requiring Python 3.9+ for the latest versions.
Fix: Ensure your project uses Python 3.9 or newer if using tblib >= 3.2.2. Refer to the changelog for specific Python version compatibility per tblib release.
breaking tblib v3.2.0 introduced changes to `tblib.pickling_support.install` to better handle custom exceptions where `__init__` does not perfectly match `BaseException.__reduce__` (e.g., `OSError` and its subclasses). This might subtly change behavior for highly customized exception types when pickling/unpickling.
Fix: Test your custom exception handling with tblib >= 3.2.0. If you encounter issues, consider explicitly defining `__reduce__` methods for complex custom exceptions, or using the `@pickling_support.install` decorator directly on your custom exception classes.
gotcha Using Python's `pickle` module for arbitrary data, including tracebacks, carries inherent security risks. Deserializing data from untrusted sources can lead to arbitrary code execution.
Fix: Only unpickle data that you trust. tblib itself notes that 'You are solely responsible for security problems should you decide to use the pickle support.'
gotcha When tracebacks are pickled, some attributes, particularly local variables within frames, are stripped for security and practical reasons. The unpickled traceback will allow re-raising or printing, but not full inspection of local state.
Fix: Be aware of this limitation; `tblib` is primarily for re-raising and printing tracebacks, not for full debugging inspection of runtime state across processes.

Install

pip install tblib Install with pip

Imports

pickling_support
```
from tblib import pickling_support
```
Traceback
```
from tblib import Traceback
```
reraise
```
from tblib.decorators import reraise
```

Quickstart

This quickstart demonstrates how to serialize an exception and its traceback using `tblib` and Python's `pickle` module. First, `pickling_support.install()` is called to enable traceback pickling. Then, `sys.exc_info()` captures the current exception, which is then serialized. Finally, the serialized exception is unpickled and its traceback can be inspected or re-raised. Note that `pickling_support.install()` typically needs to be called in the environment where the exceptions are *created* for full functionality.

import pickle
import sys
from tblib import pickling_support

def problematic_function():
    raise ValueError("Something went wrong!")

try:
    problematic_function()
except Exception:
    # Install pickling support for all imported exceptions
    pickling_support.install()
    exc_type, exc_value, exc_traceback = sys.exc_info()
    # Serialize the exception info
    serialized_exc_info = pickle.dumps((exc_type, exc_value, exc_traceback))

# In another process or later in the same process:

# Deserialize the exception info
deserialized_exc_type, deserialized_exc_value, deserialized_exc_traceback = pickle.loads(serialized_exc_info)

# Re-raise the exception with its original traceback
print(f"Caught: {deserialized_exc_type.__name__}: {deserialized_exc_value}")
print("Original traceback:\n---")
import traceback
traceback.print_tb(deserialized_exc_traceback)
print("---")

view raw JSON →