{"id":4844,"library":"viztracer","title":"VizTracer","description":"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.","status":"active","version":"1.1.1","language":"en","source_language":"en","source_url":"https://github.com/gaogaotiantian/viztracer","tags":["profiling","debugging","visualization","performance","asyncio","multiprocessing"],"install":[{"cmd":"pip install viztracer","lang":"bash","label":"Standard install"},{"cmd":"pip install viztracer[full]","lang":"bash","label":"Install with orjson for faster JSON operations"}],"dependencies":[{"reason":"Requires Python 3.10 or newer.","package":"python","optional":false},{"reason":"Improves performance for JSON dump/load operations, but is not strictly required as VizTracer falls back to the built-in json library.","package":"orjson","optional":true}],"imports":[{"symbol":"VizTracer","correct":"from viztracer import VizTracer"},{"note":"Used to access a globally registered VizTracer object for features like custom events or multi-process tracing.","symbol":"get_tracer","correct":"from viztracer import get_tracer"}],"quickstart":{"code":"from viztracer import VizTracer\n\ndef my_function():\n    total = 0\n    for i in range(1000):\n        total += i\n    return total\n\nwith VizTracer(output_file=\"result.json\") as tracer:\n    my_function()\n\n# To view the report, run in your terminal:\n# vizviewer result.json","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade to a supported Python version (currently 3.10+).","message":"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.","severity":"breaking","affected_versions":">=0.17.0"},{"fix":"Use the native flamegraph functionality available in the Perfetto UI after loading the VizTracer report.","message":"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.","severity":"breaking","affected_versions":">=0.17.0"},{"fix":"Review and update code to use the public `VizTracer` API, avoiding direct interaction with `_VizTracer`.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Use `viztracer [viztracer_args] -- [script_args]` to explicitly separate arguments.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}