Debug-friendly stack traces, with variable values and semantic highlighting

Warnings

• gotcha Python 3.12 users might encounter issues with multi-line f-strings on stackprinter versions older than 0.2.12, as a fix for this was included in version 0.2.12.
  Fix: Upgrade to stackprinter version 0.2.12 or newer (`pip install --upgrade stackprinter`).
• gotcha When handling `ExceptionGroup` objects, older stackprinter versions (prior to 0.2.11) may not fall back gracefully to default tracebacks or might crash. Version 0.2.11 introduced a fix for this.
  Fix: Upgrade to stackprinter version 0.2.11 or newer (`pip install --upgrade stackprinter`).
• gotcha In environments where standard output streams (`sys.stdout`, `sys.stderr`) are unavailable (e.g., `pythonw.exe` GUI applications), stackprinter versions older than 0.2.7 might crash when `show()` is called. Version 0.2.7 introduced graceful degradation.
  Fix: Upgrade to stackprinter version 0.2.7 or newer (`pip install --upgrade stackprinter`).
• gotcha As of version 0.2.4, verbose formatting for `KeyboardInterrupt` exceptions is disabled by default. If you require verbose tracebacks for keyboard interrupts, you must explicitly set `suppressed_exceptions=None` when calling `format()` or `show()`.
  Fix: Call `stackprinter.format(..., suppressed_exceptions=None)` or `stackprinter.show(..., suppressed_exceptions=None)`.
• gotcha When inspecting call stacks in multi-threaded programs, variable values displayed by stackprinter represent their state at the time of formatting. These values may have changed in other threads by the time the traceback is printed, potentially leading to misleading information.
  Fix: Be aware of this inherent limitation in concurrent environments. For precise state at the moment of an event, consider using a full interactive debugger.

Install

• pip install stackprinter Install latest version

Imports

• set_excepthook

  import stackprinter; stackprinter.set_excepthook()

• show

  import stackprinter; stackprinter.show()

• format

  import stackprinter; message = stackprinter.format()

• TracePrinter

  from stackprinter import TracePrinter

Quickstart

This quickstart demonstrates two ways to use stackprinter: integrating with Python's standard logging module for automatic verbose exception logging, and manually calling `stackprinter.show()` within an `except` block for immediate, enhanced traceback output. The `set_excepthook()` method (commented out) is also available to globally replace Python's default exception printout.

import stackprinter
import logging
import sys

# Option 1: Replace the default excepthook for all uncaught exceptions
# stackprinter.set_excepthook(style='darkbg')

# Option 2: Use in a try-except block or integrate with logging

class VerboseExceptionFormatter(logging.Formatter):
    def formatException(self, exc_info):
        # exc_info is a tuple (type, value, traceback)
        msg = stackprinter.format(exc_info, style='darkbg', source_lines=7, truncate_vals=200)
        return msg

def configure_logger(logger_name=None):
    formatter = VerboseExceptionFormatter('%(asctime)s %(levelname)s: %(message)s')
    handler = logging.StreamHandler(sys.stderr)
    handler.setFormatter(formatter)
    logger = logging.getLogger(logger_name)
    logger.addHandler(handler)
    logger.setLevel(logging.ERROR)
    return logger

logger = configure_logger('my_app')

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

def main():
    x = 10
    y = 0
    try:
        problematic_function(x, y)
    except ZeroDivisionError:
        logger.exception('An error occurred during calculation:')
    except TypeError as e:
        # For manual formatting and printing
        print('\n--- Manual stackprinter output ---\n')
        stackprinter.show(e, style='darkbg')

if __name__ == '__main__':
    main()