Registry / testing / better-exceptions

better-exceptions

library0.3.3pypypi✓ verified 21d ago

Better Exceptions is a Python library that automatically enhances standard Python traceback outputs, making them significantly more readable and useful for debugging. It achieves this through features like colorization, displaying more context around code lines, and printing relevant variable values at each point in the traceback. The current version is 0.3.3. It has a slow release cadence, with the last significant update (0.2.1) being several years ago, focusing on stability.

testing observability

pip install better_exceptions

github ↗package ↗

INSTALL

IMPORT

SIG · BETTER-EXCEPTIONS

better-exceptions

testingpythonv0.3.3

Install

1.5s avg

Import

55ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.3.3 · 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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.058s · 17.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.052s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

better_exceptions

✓ import better_exceptions

✗ import better_exceptions # without setting BETTER_EXCEPTIONS=1 or calling hook() in v0.2.1+

While 'import better_exceptions' is still valid for manual configuration or to call `hook()`, automatic activation in versions 0.2.1 and newer primarily relies on the BETTER_EXCEPTIONS environment variable. Simply importing might not activate the hook globally without the environment variable or an explicit `better_exceptions.hook()` call.

To quickly enable better-exceptions, set the `BETTER_EXCEPTIONS` environment variable to '1' and then run your Python script. The library will automatically hook into the exception handling system and format any uncaught exceptions.

import os os.environ['BETTER_EXCEPTIONS'] = '1' def divide_by_zero(): a = 10 b = 0 return a / b if __name__ == '__main__': try: divide_by_zero() except ZeroDivisionError: print("\n--- Better Exceptions Output (if enabled) ---") # The traceback will be formatted by better-exceptions if the hook is active. # This print statement is just to show where the formatted output would appear. raise # Re-raise to show the formatted traceback

Debug

Known issues

breakingActivation mechanism changed in v0.2.1. Previously, `import better_exceptions` was often sufficient for automatic activation. From v0.2.1 onwards, the primary method for automatic, global activation is setting the `BETTER_EXCEPTIONS=1` environment variable. Simply importing the library in newer versions may not activate the enhanced tracebacks without this environment variable or an explicit `better_exceptions.hook()` call.

fix

Ensure `export BETTER_EXCEPTIONS=1` (or `setx BETTER_EXCEPTIONS 1` on Windows) is set in your environment before running Python. Alternatively, call `better_exceptions.hook()` after importing in your script for explicit activation.

affects: >=0.2.1

gotchaDo not use `better-exceptions` in production environments. It prints detailed local variable values within tracebacks, which can leak sensitive data into logs or error reports. This is a security risk in a production setting.

fix

Always unset the `BETTER_EXCEPTIONS` environment variable or remove `better_exceptions.hook()` calls when deploying to production.

affects: All

gotchaConflicts with other exception handlers. `better-exceptions` works by replacing `sys.excepthook`. Other libraries or system tools (e.g., Ubuntu's `python3-apport`) that also modify `sys.excepthook` can interfere, preventing `better-exceptions` from functioning correctly or vice-versa.

fix

If `better-exceptions` doesn't seem to be working, check for other installed packages or system configurations that might be overriding `sys.excepthook`. Uninstall or disable conflicting components if possible.

affects: All

gotchaEnvironment variable `BETTER_EXCEPTIONS=1` is not persistent by default on Linux/OSX. Using `export` only sets it for the current terminal session.

fix

For persistent activation across sessions on Linux/OSX, add `export BETTER_EXCEPTIONS=1` to your shell's configuration file (e.g., `~/.profile`, `~/.bashrc`, or `~/.zshrc`). On Windows, use `setx BETTER_EXCEPTIONS 1` for a persistent system-wide variable.

affects: All

gotchaThere is a popular Sims 4 game mod also named 'Better Exceptions'. When searching for troubleshooting or usage information, ensure you are referencing documentation for the Python library and not the game mod, as they are entirely unrelated projects.

fix

Always verify the context of search results to ensure they refer to the Python library `better-exceptions` by checking the domain (e.g., GitHub for the Python project, PyPI) or content specific to Python development.

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'better_exceptions'

The `better-exceptions` package is not installed in the current Python environment or the Python interpreter cannot locate it in its search path.

fix

Install the package using pip: `pip install better-exceptions`

better-exceptions not working / no beautiful exceptions / traceback not colored

The `better-exceptions` hook is not activated, often because the necessary environment variable `BETTER_EXCEPTIONS` is not set or its value is not recognized, or because another library has overridden `sys.excepthook`.

fix

Set the environment variable `BETTER_EXCEPTIONS=1` before running your script (e.g., `export BETTER_EXCEPTIONS=1` on Linux/macOS or `set BETTER_EXCEPTIONS=1` on Windows). Alternatively, manually activate it at the beginning of your script with `import better_exceptions; better_exceptions.hook()`.

Error in sys.excepthook: Original exception was: AttributeError: 'NoneType' object has no attribute 'error' (or similar errors related to `sys.excepthook` conflicts)

Another library or framework (like IPython, unittest, or certain logging configurations) is also modifying or interfering with Python's `sys.excepthook`, preventing `better-exceptions` from correctly processing or displaying exceptions.

fix

Manually ensure `better_exceptions.hook()` is called after other potential `sys.excepthook` modifications, or investigate if specific integrations (e.g., for Django) are needed, or if an uninstall of conflicting packages (like `python3-apport` on Ubuntu) is required.

ModuleNotFoundError: No module named 'colorama'

The `colorama` package, which is a dependency for `better-exceptions` to provide colored output, is missing or incorrectly installed.

fix

Install the `colorama` package: `pip install colorama`. If it's already installed, try reinstalling both `colorama` and `better-exceptions`.

Upgrade

Version history

0.3.3latest on PyPI · released Jan 29, 2021

Audit

Dependencies

No dependency data recorded yet.

Agent activity

39 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/qix-/better-exceptions ↗

packagehttps://pypi.org/project/better-exceptions/ ↗