tblib: Traceback Serialization Library

3.2.2 verified Tue May 12 auth: no python install: verified

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.

pip install tblib

Common errors

error TypeError: cannot pickle 'frame' object ↓

cause This error occurs when attempting to pickle an exception or a traceback object directly without enabling tblib's custom pickling support.

fix

Call tblib.pickling_support.install() at the beginning of your script or process to enable tblib's custom pickling handlers for tracebacks.

error ModuleNotFoundError: No module named 'tblib.pickling_support' ↓

cause The `tblib` library is either not installed in the current Python environment, or the specific submodule `pickling_support` is referenced incorrectly.

fix

Install tblib using pip: pip install tblib. Ensure the import statement is import tblib.pickling_support or from tblib.pickling_support import install.

error TypeError: Cannot create a Traceback from object of type <class 'NoneType'> ↓

cause This error occurs when `tblib.Traceback()` is called with `None` as an argument, typically because `sys.exc_info()[2]` was accessed outside an active exception context.

fix

Ensure that tblib.Traceback() is called only when an exception is actively being handled, so sys.exc_info()[2] yields a valid traceback object.

error NameError: name 'tblib' is not defined ↓

cause This error occurs when attempting to call `tblib.pickling_support.install()` without first importing the `tblib` package or its `pickling_support` submodule into the current scope.

fix

Ensure you have either import tblib.pickling_support (and then call tblib.pickling_support.install()) or from tblib.pickling_support import install (and then call install()).

error AttributeError: 'Traceback' object has no attribute 'lineno' ↓

cause This error occurs when trying to access frame-specific attributes like `lineno` directly on a `tblib.Traceback` object, instead of on individual frame objects within it.

fix

Iterate through the tblib.Traceback object's frames attribute and access frame-specific information from each frame object: for frame in tb_obj.frames: print(frame.lineno).

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 compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.00s 17.8M

3.10 alpine (musl) - - 0.00s 17.8M

3.10 slim (glibc) wheel 1.5s 0.00s 18M

3.10 slim (glibc) - - 0.00s 18M

3.11 alpine (musl) wheel - 0.00s 19.7M

3.11 alpine (musl) - - 0.00s 19.7M

3.11 slim (glibc) wheel 1.6s 0.00s 20M

3.11 slim (glibc) - - 0.00s 20M

3.12 alpine (musl) wheel - 0.00s 11.6M

3.12 alpine (musl) - - 0.00s 11.6M

3.12 slim (glibc) wheel 1.5s 0.00s 12M

3.12 slim (glibc) - - 0.00s 12M

3.13 alpine (musl) wheel - 0.00s 11.3M

3.13 alpine (musl) - - 0.00s 11.2M

3.13 slim (glibc) wheel 1.4s 0.00s 12M

3.13 slim (glibc) - - 0.00s 12M

3.9 alpine (musl) wheel - 0.00s 17.3M

3.9 alpine (musl) - - 0.00s 17.3M

3.9 slim (glibc) wheel 1.8s 0.00s 18M

3.9 slim (glibc) - - 0.00s 18M

Imports

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

Quickstart last tested: 2026-04-24

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("---")