viztracer

library1.1.1pypypi✓ verified 26d ago

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.

observability testing

pip install viztracer

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · VIZTRACER

viztracer

observabilitypythonv1.1.1

Install

2.6s avg

Import

84ms

Disk

62MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.1.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

build_error

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 2.6s · import 0.084s · 67MB

62MB installed

● package 62MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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

viztracer --version

Debug

Known issues

breakingVizTracer 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+).

affects: >=0.17.0

breakingThe 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.

affects: >=0.17.0

breakingVersion 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`.

affects: >=1.0.0

gotchaVizTracer 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.

affects: All

gotchaFor 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.

affects: All

gotchaWhen 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.

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'viztracer'

The `viztracer` package has not been installed in the current Python environment.

fix

pip install viztracer

viztracer: command not found

The `viztracer` command-line tool is not found in your system's PATH, usually because the package was not installed or its executable script directory is not recognized.

fix

Ensure `viztracer` is installed (`pip install viztracer`) and your Python environment's script directory (e.g., `~/.local/bin` or your virtual environment's `bin/Scripts` folder) is included in your system's PATH.

Error: trace_data.json not found.

The `vizviewer` command was executed without specifying a trace file and the default `trace_data.json` file was not found in the current directory.

fix

Run `viztracer` on your code to generate a trace file (e.g., `viztracer your_script.py`), or specify the correct path to an existing trace file (e.g., `vizviewer my_trace.json`).

RuntimeError: VizTracer has already been started

The `VizTracer.start()` method was called on an already active `VizTracer` instance, as a `VizTracer` object can only be started once.

fix

Ensure `VizTracer.start()` is called only once per `VizTracer` instance; if you need to trace multiple independent sections, create new `VizTracer` instances or use `VizTracer.pause()` and `VizTracer.resume()`.

Upgrade

Version history

1.1.1latest on PyPI · released Nov 11, 2025

Audit

Dependencies

pythonrequiredRequires Python 3.10 or newer.

orjsonoptionalImproves performance for JSON dump/load operations, but is not strictly required as VizTracer falls back to the built-in json library.

Agent activity

39 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/gaogaotiantian/viztracer ↗

packagehttps://pypi.org/project/viztracer/ ↗

docshttps://viztracer.readthedocs.io ↗