Colored Traceback

Common errors

• Tracebacks appear with unexpected or double coloring on Python 3.13+.

  cause Conflict with Python 3.13's built-in colored traceback feature.
  fix Remove `colored-traceback` from your environment if using Python 3.13 or newer, or investigate methods to disable Python's native colorization if you prefer `colored-traceback`'s output.

• Tracebacks are monochrome (not colored) when running my script and piping output to another tool or saving to a file.

  cause By default, `colored-traceback` disables color output when `stderr` is not detected as an interactive terminal (TTY).
  fix Modify your activation call to `colored_traceback.add_hook(always=True)` or use the convenience import `import colored_traceback.always`.

• AttributeError: module 'colored_traceback' has no attribute 'auto' (or 'always' or 'add_hook')

  cause Incorrect import statement or a damaged/incomplete installation.
  fix Ensure you are importing correctly as `import colored_traceback.auto`, `import colored_traceback.always`, or `import colored_traceback` followed by `colored_traceback.add_hook()`. If the issue persists, try reinstalling the package: `pip uninstall colored-traceback && pip install colored-traceback`.

Warnings

• breaking Python 3.13 and newer versions introduce native colorized tracebacks. Using `colored-traceback` with Python 3.13+ may lead to unexpected behavior, double coloring, or conflicts with the built-in system.
  Fix: On Python 3.13+, consider removing `colored-traceback` and relying on the interpreter's native colorization. If `colored-traceback` specific features are required, test thoroughly for conflicts or ensure native coloring is disabled if possible via `PYTHON_COLORS=0` or `NO_COLOR` environment variables.
• gotcha Tracebacks may not appear colored when the output (stderr) is redirected or piped to another command/file.
  Fix: Use `colored_traceback.add_hook(always=True)` or `import colored_traceback.always` to force color output even when stderr is not a TTY.
• gotcha On Windows, `colored-traceback` automatically installs the `colorama` package to provide ANSI escape sequence support, which might be an unexpected dependency for some users.
  Fix: Ensure `colorama` is installed if you encounter issues with coloring on Windows. If `colorama` is not desired, `colored-traceback` is not suitable for Windows environments requiring minimal dependencies.

Install

• pip install colored-traceback Install stable version

Imports

• add_hook
  wrong:

  from colored_traceback import add_hook # Direct import of add_hook is not the intended primary usage for activation.

  correct:

  import colored_traceback
  colored_traceback.add_hook()

  The add_hook() function is typically called directly from the colored_traceback module to install the exception hook.
• auto

  import colored_traceback.auto

  A convenience import that automatically calls add_hook().
• always

  import colored_traceback.always

  A convenience import that automatically calls add_hook(always=True) to force color output even when stderr is piped.

Quickstart

This quickstart demonstrates how to activate colored tracebacks by simply importing `colored_traceback.auto`. Running this script will cause a `ZeroDivisionError` and display a colorized traceback in your terminal.

import colored_traceback.auto

def cause_error():
    return 1 / 0

def main():
    print("Attempting to cause an error...")
    cause_error()

if __name__ == "__main__":
    main()