VizTracer

1.1.1 · active · verified Sun Apr 12

VizTracer is a low-overhead logging, debugging, and profiling tool for Python that traces and visualizes code execution on a timeline. It supports multi-threading, multi-processing, asyncio, and PyTorch, and the front-end UI is powered by Perfetto. The current version is 1.1.1, and it has a regular release cadence with recent releases approximately every 1-2 months.

Warnings

breaking VizTracer has periodically dropped support for older Python versions. Version 1.1.0 dropped Python 3.9 (supporting 3.14+), and version 0.17.0 dropped Python 3.8 (supporting 3.13+). Ensure your Python environment meets the current `requires_python` specification.
Fix: Upgrade to a supported Python version (currently 3.10+).
breaking The native flamegraph feature was removed in version 0.17.0 because Perfetto, the underlying UI, supports flamegraphs natively. Users previously relying on VizTracer's direct flamegraph generation should use Perfetto's built-in functionality.
Fix: Use the native flamegraph functionality available in the Perfetto UI after loading the VizTracer report.
breaking Version 1.0.0 'polished the interface and APIs of C tracer to fully eliminate the middleware _VizTracer'. If your code directly interacted with the internal `_VizTracer` middleware, these integrations will break.
Fix: Review and update code to use the public `VizTracer` API, avoiding direct interaction with `_VizTracer`.
gotcha VizTracer uses a circular buffer to store trace entries. For very large or long-running programs, this can consume significant RAM and disk space (default 1,000,000 entries ≈ 150MiB disk, with substantial pre-allocated RAM). This can lead to out-of-memory errors or truncated traces if the buffer is exhausted.
Fix: Adjust the circular buffer size (`buffer_size` parameter in `VizTracer` or `--buffer_size` via CLI) or use trace filters (`--include_files`, `--exclude_files`, `--max_stack_depth`, `--log_sparse`) to reduce the amount of data collected.
gotcha For complex scenarios like multiprocessing, subprocess tracing, or other advanced features, invoking VizTracer from the command line (`viztracer my_script.py`) is generally preferred over inline usage. Inline `VizTracer` might not fully support all such capabilities, and specific invocation patterns (e.g., passing a list of arguments to `subprocess.Popen`) are required for features like subprocess patching to work.
Fix: Whenever possible, use the command-line interface for profiling scripts with multiprocessing or subprocesses. Refer to the official documentation for specific concurrency tracing configurations.
gotcha When running VizTracer from the command line, if your script also requires arguments, you must separate VizTracer's arguments from your script's arguments using `--`. Forgetting this can lead to incorrect parsing of arguments or errors.
Fix: Use `viztracer [viztracer_args] -- [script_args]` to explicitly separate arguments.

Install

pip install viztracer Standard install
pip install viztracer[full] Install with orjson for faster JSON operations

Imports

VizTracer
```
from viztracer import VizTracer
```
get_tracer
```
from viztracer import get_tracer
```
Used to access a globally registered VizTracer object for features like custom events or multi-process tracing.

Quickstart

This example demonstrates inline usage of VizTracer as a context manager to profile a Python function. After execution, a 'result.json' file is generated, which can be opened and visualized with the `vizviewer` command-line tool.

from viztracer import VizTracer

def my_function():
    total = 0
    for i in range(1000):
        total += i
    return total

with VizTracer(output_file="result.json") as tracer:
    my_function()

# To view the report, run in your terminal:
# vizviewer result.json

view raw JSON →