---
id: viztracer
version: "1.1.1"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# viztracer — A debugging and profiling tool that can trace and visualize python code execution

License: permissive · Maintenance: active · Downloads: 1.7M/mo

## What it is and what it does

VizTracer is a low-overhead execution tracer that records function entry and exit events, then visualizes them in an interactive timeline UI powered by Perfetto. It works as a command-line tool (no code changes needed for basic tracing) or as an inline context manager for programmatic control. The tracer captures detailed timing information and renders it in a browser-based viewer that supports zooming, filtering, and flamegraph generation.

The tool is designed to handle concurrent code: it natively supports threading (Python 3.12+ without modification, earlier versions with native threading module), multiprocessing, subprocess, asyncio, and PyTorch profiling. It also supports remote attach to running processes and can log extra information like variable values, function arguments, and exceptions without modifying source code. The fact sheet indicates it is actively maintained, production-stable, and has no known security vulnerabilities.

Use it for:

- Identify performance bottlenecks in CPU-bound Python code by visualizing which functions consume the most time
- Debug multi-threaded or async applications by seeing how threads and coroutines interleave and where blocking occurs
- Profile PyTorch model training to understand GPU event timing and native call overhead
- Trace subprocess and multiprocessing workflows to understand inter-process communication and timing
- Generate flamegraphs from trace data to quickly spot hot code paths in large applications

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

VizTracer traces Python code execution and generates interactive visualizations showing function calls, timing, and execution flow across threads, processes, and async code.

Yes. VizTracer is a mature, actively maintained profiler with no security issues, minimal dependencies, and broad platform support. It solves a real problem (understanding code execution flow and performance) with low overhead and a polished UI. The Apache-2.0 license is permissive. Install it if you need to profile or debug Python execution; the command-line interface requires no code changes for initial exploration.

## Install

pip install viztracer
uv add viztracer
poetry add viztracer

## Installing viztracer

Before you install: Medium install friction due to compiled wheels for multiple platforms and Python versions (3.10–3.14). Active maintenance with recent commits and stable production status. Single runtime dependency (objprint) keeps the dependency surface minimal.

License in practice: Apache-2.0 permissive license allows commercial and private use with minimal restrictions, making it suitable for most development and production environments.

Quickstart:

pip install viztracer

# Command line: trace a script
viztracer my_script.py arg1 arg2

# Or inline in code:
from viztracer import VizTracer
tracer = VizTracer()
tracer.start()
# code to trace
tracer.stop()
tracer.save()

Requires Python 3.10 or later. Compiled wheels available for Linux, macOS, and Windows; source build may require a C compiler on unsupported platforms.

Verify before relying:

- Exact overhead percentage for typical real-world applications (description mentions 'below 1x' but measurement methodology unclear)
- Whether orjson is automatically installed or only recommended as optional for faster JSON export

## Package facts

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 1.7M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

python code profiler tracer, execution timeline visualization, function call tracing, performance debugging tool, low-overhead profiler, thread-aware tracer, async code profiler, profiling, debugging, performance-analysis

[View on SkillFed](https://skillfed.io/packages/viztracer) · [View on PyPI](https://pypi.org/project/viztracer/)