{"id":2055,"library":"gprof2dot","title":"gprof2dot","description":"gprof2dot is a Python script that converts the output from various profilers (e.g., cProfile, gprof, Valgrind callgrind, Linux perf, Java HPROF) into a Graphviz dot graph. This allows for visual analysis of performance bottlenecks and call flows within an application. The library is actively maintained with a current version of 2025.4.14, typically releasing updates on a yearly or bi-yearly basis.","status":"active","version":"2025.4.14","language":"python","source_language":"en","source_url":"https://github.com/jrfonseca/gprof2dot","tags":["profiling","visualization","performance","call graph","developer tools"],"install":[{"cmd":"pip install gprof2dot","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Requires Python 3.8 or newer to run the script.","package":"python","optional":false},{"reason":"Required externally to render the '.dot' graph files into images (e.g., PNG, SVG). Not installed by pip.","package":"graphviz","optional":false}],"imports":[{"note":"While primarily a command-line tool, gprof2dot also exposes a Python API for programmatic use, allowing direct parsing and graph generation without subprocess calls.","symbol":"gprof2dot","correct":"import gprof2dot"}],"quickstart":{"code":"# 1. Profile your Python code (e.g., using cProfile)\nimport cProfile\nimport time\n\ndef my_function():\n    time.sleep(0.1)\n    another_function()\n\ndef another_function():\n    time.sleep(0.05)\n\nif __name__ == \"__main__\":\n    profiler = cProfile.Profile()\n    profiler.enable()\n    my_function()\n    profiler.disable()\n    profiler.dump_stats(\"output.pstats\")\n    print(\"Profile data saved to output.pstats\")\n\n# 2. Convert the .pstats file to a .dot graph and render with Graphviz\n#    Run this from your terminal after the Python script above:\n#    gprof2dot -f pstats output.pstats | dot -Tpng -o output.png\n#    (Ensure 'dot' command from Graphviz is in your PATH)","lang":"python","description":"To use gprof2dot, first profile your application using a compatible profiler (e.g., Python's `cProfile`). Save the profiling output to a file. Then, use the `gprof2dot` command-line tool to convert this profiling data into the Graphviz DOT language, piping the output to the `dot` command (from Graphviz) to generate a visual graph image (e.g., PNG or SVG)."},"warnings":[{"fix":"Install Graphviz separately and ensure its `dot` executable is in your system's PATH.","message":"gprof2dot requires an external tool, Graphviz, to render the generated '.dot' files into visual graphs (like PNG or SVG). `pip install gprof2dot` does NOT install Graphviz. You must install Graphviz separately (e.g., `sudo apt-get install graphviz` on Debian/Ubuntu, or from its official website). Without Graphviz, the `dot` command will not be found, and image generation will fail.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure you are running gprof2dot with Python 3.8 or a later version.","message":"Support for Python 2.x has been dropped. gprof2dot now officially requires Python 3.8 or newer. Attempts to run on older Python versions will likely result in errors.","severity":"breaking","affected_versions":"< 2024.06.06"},{"fix":"Be aware of `gprof`'s limitations. For C/C++ profiling, consider alternative profilers like Valgrind's Callgrind or Linux `perf` for more accurate call graph information. Always compile with the `-pg` flag for `gprof` to work.","message":"When profiling C/C++ code with `gprof`, the resulting call graph data can sometimes be inaccurate or flaky. This can lead to misleading visualizations where the 'main' function isn't the root, or library functions appear as top-level callers. This is a limitation of `gprof` itself, not `gprof2dot`.","severity":"gotcha","affected_versions":"All versions (when using gprof input)"},{"fix":"Use the `-s` / `--strip` option to remove function parameters, template parameters, and const modifiers, or the `-w` / `--wrap` option to wrap long labels for better readability.","message":"Node labels in the generated graphs can become excessively long, especially when profiling C++ code with complex template names, scope information, or function arguments. This can make the graph unreadable.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Users should be aware of the project's maintenance status and manage expectations for new features or rapid bug fixes.","message":"The project maintainer has indicated having 'little or no time for its maintenance', implying that new features are unlikely and response times for issues/pull requests may be slow. While the tool remains functional and receives occasional updates, active development for new features is not a priority.","severity":"gotcha","affected_versions":"2025.04.14 and later"}],"env_vars":null,"search_vec":"'2025.4.14':52 'activ':45 'allow':29 'analysi':32 'applic':41 'basi':63 'bi':61 'bi-year':60 'bottleneck':35 'call':37,67 'callgrind':18 'convert':8 'cprofil':15 'current':49 'develop':69 'dot':26 'e.g':14 'flow':38 'gprof':16 'gprof2dot':1,2 'graph':27,68 'graphviz':25 'hprof':22 'java':21 'librari':43 'linux':19 'maintain':46 'output':10 'perf':20 'perform':34,66 'profil':13,64 'python':5 'releas':54 'script':6 'tool':70 'typic':53 'updat':55 'valgrind':17 'various':12 'version':50 'visual':31,65 'within':39 'year':58,62","created_at":"2026-04-09T18:41:35.683864+00:00","updated_at":"2026-04-16T18:55:04.487027+00:00","problems":[{"fix":"Run the script using `python -m gprof2dot` if installed via pip, or ensure the directory containing `gprof2dot` is added to your system's PATH, or execute it directly with `python gprof2dot.py` if downloaded.","cause":"The `gprof2dot` script is not in your system's PATH, or Python is not explicitly used to run it.","error":"gprof2dot: command not found"},{"fix":"Install Graphviz on your system (e.g., `sudo apt-get install graphviz` on Debian/Ubuntu, `brew install graphviz` on macOS) and ensure its executable is in your system's PATH.","cause":"The Graphviz `dot` command-line tool, which `gprof2dot` uses to render the graph, is not installed or not accessible in your system's PATH.","error":"gprof2dot: error: Graphviz's 'dot' tool not found."},{"fix":"Verify that the input file is valid, correctly generated by the profiler, and that the correct format is specified using the `-f` flag (e.g., `-f python` for `cProfile` outputs, `-f callgrind` for Valgrind outputs).","cause":"The input file is either corrupted, empty, does not match the specified format (`-f` flag), or the format was incorrectly auto-detected (e.g., missing `-f python` for `cProfile` dumps).","error":"gprof2dot: error: could not parse input as python profile data"},{"fix":"Use one of the valid format choices listed in the error message, such as `python` for `cProfile` outputs, `callgrind` for Valgrind outputs, or `perf` for Linux `perf` data.","cause":"An incorrect or unsupported profiler format name was provided to the `-f` or `--format` argument.","error":"gprof2dot: error: argument -f/--format: invalid choice: 'cprofile' (choose from 'callgrind', 'perf', 'python', 'hprof', 'oprofile', 'gprof')"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2025.4.14","cli_name":"gprof2dot","cli_version":"Usage:","type":"library","homepage":"https://gprof2dot.jrf.org","github":"https://github.com/jrfonseca/gprof2dot","docs":null,"changelog":null,"pypi":"https://pypi.org/project/gprof2dot/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing","observability"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}