traceback_with_variables prints the locals of every frame when Python raises

The gap between the line that raised and the state that caused it

A Python traceback tells you where an exception was raised and what the exception message was. It does not tell you what the variables in that frame held, which is usually the question you actually have. The package description states the problem directly: it adds variables to the Python traceback, debugging the reasons for exceptions by logging or pretty printing colorful variable contexts for each frame in a stacktrace, showing every value, and dumping the locals environment after errors to the console, to files and to loggers. The audience is developers working in small to medium applications who want the state without writing a print statement for every variable in every function, and the project's own summary of it is that it is very simple to use and fast but versatile when needed, meant for debugging and kept for small scale production.

Four entry points, from whole program to single block

The library offers a gradient of control, and picking the right one is the main decision. For a whole program, the simplest usage is a single import:

    from traceback_with_variables import activate_by_import

or, if you installed the interactive alias described below, a shorter import:

    import tb.a

For a single function, a decorator is used:

    @prints_exc
    # def main(): or def some_func(...):

For a single code block, a context manager:

    with printing_exc():

And for the case where you want the stack without an exception, there is a direct call:

    print_cur_tb()

That last one is the one people tend to forget, and it is the most useful in a debugger or a REPL, where you want the current frame state on demand rather than after a failure. The decorator and the context manager are the two that scale, since they can be applied to the entry points of a subsystem rather than to a whole program.

The console script wraps a script without editing it

The most interesting entry point is the one that requires no code change at all. The package installs a console script, declared in setup.py as traceback-with-variables pointing at traceback_with_variables.main:main, and the README shows it used to run an existing script, command or module:

traceback-with-variables tested_script.py ...srcipt's args...

The arguments after the script name are passed through to your script, which is what makes this usable on a real command line rather than only in a demo. For an environment where you cannot touch the source, or where you want to compare a failing run with and without the variable dump, this is the practical route. The examples directory backs it up with external_script.sh. There is also a shorter interactive alias, created once with:

python3 -c 'from traceback_with_variables.tb_alias import create_tb_alias as c; c()'

which is what makes the `import tb.a` form available in a REPL.

One fmt object controls what gets printed

Customisation is not spread across a dozen parameters, it sits on a single formatting object that the README shows being configured directly:

    from traceback_with_variables import fmt
    fmt.max_value_str_len = 10000
    fmt.skip_files_except = 'my_project'
    fmt.custom_var_printers = []  # show all variables, no skips, no hides

Three knobs there, and they cover the questions that come up in practice. How long a single value may be before it is truncated, which files the dump applies to, and which variables to skip entirely. The last one defaults to hiding something, and the comment on the empty list says that an empty list means show all variables with no skips and no hides, so the default behaviour is conservative and you opt in to more output. The examples folder also contains change_global_printer.py and its Jupyter counterpart, which is how you replace the default printer entirely rather than tuning it. Colour is part of the output format too, and the README points at a discussion of ANSI colour handling in the Windows console, which is the usual stumbling block when coloured tracebacks meet a terminal that does not interpret them.

The same dump can go to a file or into a logger

The output target is a parameter rather than a separate API, which is what lets the same code serve a developer at a terminal and a service writing to its log pipeline. With a logger, the context manager and the decorator take a file_ argument, and a LoggerAsFile adapter bridges the gap:

    with printing_exc(file_=LoggerAsFile(logger)):
    # or
    @prints_exc(file_=LoggerAsFile(logger)): 

If you want the traceback lines themselves rather than the printed form, there is an iterator over them:

    lines = list(iter_exc_lines(e))

That is the hook for anything the library does not do for you, such as shipping the frames to a monitoring service or reformatting them into your own structure. In an interactive session after an exception has already been caught, the README shows a single call:

    >>> print_exc()

The examples directory lists the variants by name, with log_for_function.py, log_for_code_block.py, print_for_function.py, print_for_code_block.py, print_cur_tb.py, print_traceback.py, work_with_traceback_lines.py, interactive_print_last_exception.py, change_global_printer.py, flask.py, secret_data.py, simple.py, simple_jupyter.py and a colab notebook, which is a fairly complete map of the API surface.

Zero dependencies, full typing, and a large test suite

The badges in the README make a few claims that are worth taking at face value because they are checkable in the repository. The dependency count is zero, and the setup.py file confirms it, listing no install_requires at all, with a test extra that pulls in flake8 and ipython for the suite. The type hints coverage badge points at the override module in the package and claims full annotations, and a second badge claims no object oriented programming, only transparent functions and data classes, which is a design choice rather than a metric. The test badge claims 9328 tests and the coverage badge claims 100 percent, both pointing at the tests directory, and the CI badge points at a GitHub Actions workflow. The package supports Python 3.6 and newer, is marked as operating system independent, and is published to both PyPI and conda-forge under the name traceback-with-variables, with the distribution name using hyphens and the import name in module form.

Releases are sparse, and the README names a version that has no tag

The maintenance picture is modest. The release history in the repository shows v2.2.0 on 2025-02-21, v2.0.4 on 2021-12-05 and v1.1.9 on 2020-11-22, so the gap between the first two of those is nearly four years, and the newest release is from early 2025. The last push was on 2026-07-30, so commits continue after that release, and the repository is not archived. There is also a small inconsistency worth knowing about: the installation commands in the README ask for version 2.2.1, while the newest release tag listed is v2.2.0, which suggests the packaged version and the tag are not kept in lockstep, or that a 2.2.1 exists without a matching tag. The README also mentions a next_version branch where work in progress lives, and invites proposals, which is the usual pattern for a project that releases carefully. The licence is MIT, with the LICENSE file at the repository root.

Editorial conclusion

Adopt traceback_with_variables if you lose time to exceptions whose message says nothing about the state that produced them, since it shows the variables of every frame automatically and works in Jupyter as well as in scripts, with no dependency to install. Do not adopt it in a pipeline that logs secrets into files, since the whole point is to print every local value, and the README includes an example file named secret_data.py, so you need to know exactly what ends up in your logs. Before you ship it, set the formatting limits and any skip rules, decide whether the output belongs in your logging pipeline or only on the console, and check the version you install, because the README's install commands name 2.2.1 while the newest release tag is v2.2.0.

Frequently asked questions

Official sources

1. andy-landy/traceback_with_variables on GitHub
2. Issues
3. License: MIT
4. README
5. Releases