Tracerite: Human-Readable Exception Tracebacks

2.3.1 · active · verified Sat Apr 11

Tracerite is a Python library that transforms standard Python exception tracebacks into highly readable HTML or formatted TTY output. It is actively maintained, with frequent releases (current version 2.3.1), providing features like chronological ordering of chained exceptions, minimalistic output by pruning irrelevant details, and variable inspection across various environments, including terminals, Jupyter notebooks, and web frameworks like FastAPI and Sanic.

Warnings

breaking Version 2.0.0 was a complete rewrite, fundamentally changing internal data structures and relying heavily on Python 3.11+'s enhanced exception handling features. Code that interacted with Tracerite's internal APIs from 1.x will break.
Fix: Review the official documentation and update your integration code for Tracerite 2.x. Ensure your Python environment is 3.9+ (preferably 3.11+ for full feature leverage).
gotcha Tracerite.load() overwrites `sys.excepthook`. If you have a custom exception hook, `tracerite.load()` will replace it. You may need to manually chain your custom hook with Tracerite's or conditionally load Tracerite.
Fix: Save the original `sys.excepthook` before calling `tracerite.load()`, and call the original hook within your custom handler if Tracerite doesn't handle the exception, or vice-versa. For web frameworks, use specific integration functions like `patch_fastapi()`.
gotcha While Tracerite's `requires_python` is `>=3.9`, many of the advanced features introduced in v2.0.0, particularly exact cursor positions and optimized exception chain analysis, are based on Python 3.11+'s improved exception handling.
Fix: For the best experience and full functionality, run Tracerite on Python 3.11 or newer. If on Python 3.9 or 3.10, functionality will be present but might lack some of the granular detail available on newer Python versions.
deprecated Version 1.x series has reached its end of life with v1.2.0. Future development and bug fixes are exclusively in the 2.x series.
Fix: Upgrade to Tracerite 2.x. Be aware of the breaking changes mentioned for v2.0.0.
gotcha Tracerite v2.3.0 introduced a significant change in how chained exceptions are presented, adopting a single chronological timeline rather than Python's default convoluted order.
Fix: This is generally an improvement for readability. If you had automation or tools parsing previous output formats, they might need adjustment.

Install

pip install tracerite Install stable release

Imports

load
```
import tracerite; tracerite.load()
```
Activates Tracerite for all subsequent uncaught exceptions by modifying sys.excepthook.
patch_fastapi
```
from tracerite import patch_fastapi; patch_fastapi()
```
Integrates Tracerite with FastAPI/Starlette's error handling to provide HTML tracebacks in debug mode.

Quickstart

This quickstart demonstrates how to enable Tracerite for all uncaught exceptions in a Python script. Simply import `tracerite` and call `tracerite.load()`. Any subsequent unhandled exception will be processed and displayed in a human-readable format, either in the terminal or as HTML in compatible environments.

import tracerite

tracerite.load()

def divide_by_zero(a, b):
    result = a / b
    return result

def main():
    x = 10
    y = 0
    print(f"Attempting to divide {x} by {y}")
    divide_by_zero(x, y)

if __name__ == '__main__':
    try:
        main()
    except Exception:
        # Tracerite will automatically handle uncaught exceptions
        # You won't typically wrap main() in a try-except if using tracerite.load()
        # This is just to show the immediate effect if not letting it propagate.
        pass

# When run, this will output a formatted traceback to stderr (TTY) or HTML (Jupyter/Web)

view raw JSON →