Better Exceptions

Warnings

• breaking Activation 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.
• gotcha Do 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.
• gotcha Conflicts 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.
• gotcha Environment 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.
• gotcha There 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.

Install

• pip install better_exceptions Install with pip

Imports

• better_exceptions

  import better_exceptions

  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.

Quickstart

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