Install & Compatibility
Where this runs
tested against v2.6.5 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.316s · 18.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.276s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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)
tracerite --version
Debug
Known issues
breakingVersion 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.fixReview 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).
affects: >=2.0.0
gotchaTracerite.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.fixSave 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()`.
affects: All versions
gotchaWhile 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.fixFor 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.
affects: >=2.0.0 on Python <3.11
deprecatedVersion 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.fixUpgrade to Tracerite 2.x. Be aware of the breaking changes mentioned for v2.0.0.
affects: <2.0.0
gotchaTracerite 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.fixThis is generally an improvement for readability. If you had automation or tools parsing previous output formats, they might need adjustment.
affects: >=2.3.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'tracerite'
The tracerite library has not been installed in the current Python environment.
TypeError: 'module' object is not callable
The 'tracerite' module itself is not a callable function; its functionality is accessed through its methods.
fixUse specific functions like `tracerite.install()` to activate the custom traceback hook or `tracerite.html(exc, tb)` to format an exception directly.
TypeError: html() missing 1 required positional argument: 'traceback'
The `tracerite.html()` (or `tracerite.text()`) function requires both an exception object and a traceback object as arguments.
fixEnsure both the exception and the traceback (e.g., obtained from `sys.exc_info()` or `e.__traceback__`) are passed: `import sys; result = tracerite.html(e, sys.exc_info()[2])` or `result = tracerite.html(e, e.__traceback__)`.
Upgrade
Version history
2.6.5latest on PyPI · released Aug 18, 2026
Audit
Dependencies
No dependency data recorded yet.