{"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":"python","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,"search_vec":"'-2':63 '1':62 '1.1.1':49 'approxim':60 'asyncio':32,69 'cadenc':56 'code':19 'current':46 'debug':9,66 'end':39 'everi':61 'execut':20 'front':38 'front-end':37 'log':8 'low':6 'low-overhead':5 'month':64 'multi':27,30 'multi-process':29 'multi-thread':26 'multiprocess':70 'overhead':7 'perfetto':44 'perform':68 'power':42 'process':31 'profil':11,65 'python':14 'pytorch':34 'recent':58 'regular':54 'releas':55,59 'support':25 'thread':28 'timelin':23 'tool':12 'trace':16 'ui':40 'version':47 'visual':18,67 'viztrac':1,2","created_at":"2026-04-12T14:10:01.020938+00:00","updated_at":"2026-04-17T00:18:46.306247+00:00","problems":[{"fix":"pip install viztracer","cause":"The `viztracer` package has not been installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'viztracer'"},{"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.","cause":"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.","error":"viztracer: command not found"},{"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`).","cause":"The `vizviewer` command was executed without specifying a trace file and the default `trace_data.json` file was not found in the current directory.","error":"Error: trace_data.json not found."},{"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()`.","cause":"The `VizTracer.start()` method was called on an already active `VizTracer` instance, as a `VizTracer` object can only be started once.","error":"RuntimeError: VizTracer has already been started"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.1.1","cli_name":"viztracer","cli_version":"1.1.1","type":"library","homepage":null,"github":"https://github.com/gaogaotiantian/viztracer","docs":"https://viztracer.readthedocs.io","changelog":null,"pypi":"https://pypi.org/project/viztracer/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["observability","testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-30","next_check":"2026-07-28","install_tag":null}}