gprof2dot

library2025.4.14pypypi✓ verified 23d ago

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.

testing observability

pip install gprof2dot

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GPROF2DOT

gprof2dot

testingpythonv2025.4.14

Install

1.8s avg

Import

42ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2025.4.14 · 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.95 runs

installs and imports cleanly · install 0.0s · import 0.042s · 18MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.8s · import 0.042s · 19MB

16MB installed

● package 16MB

Code

Verified usage

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

gprof2dot

✓ import gprof2dot

While primarily a command-line tool, gprof2dot also exposes a Python API for programmatic use, allowing direct parsing and graph generation without subprocess calls.

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

# 1. Profile your Python code (e.g., using cProfile) import cProfile import time def my_function(): time.sleep(0.1) another_function() def another_function(): time.sleep(0.05) if __name__ == "__main__": profiler = cProfile.Profile() profiler.enable() my_function() profiler.disable() profiler.dump_stats("output.pstats") print("Profile data saved to output.pstats") # 2. Convert the .pstats file to a .dot graph and render with Graphviz # Run this from your terminal after the Python script above: # gprof2dot -f pstats output.pstats | dot -Tpng -o output.png # (Ensure 'dot' command from Graphviz is in your PATH)

gprof2dot --version

Debug

Known issues

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

fix

Install Graphviz separately and ensure its `dot` executable is in your system's PATH.

affects: All versions

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

fix

Ensure you are running gprof2dot with Python 3.8 or a later version.

affects: < 2024.06.06

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

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.

affects: All versions (when using gprof input)

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

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.

affects: All versions

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

fix

Users should be aware of the project's maintenance status and manage expectations for new features or rapid bug fixes.

affects: 2025.04.14 and later

Errors

Common errors & fixes

gprof2dot: command not found

The `gprof2dot` script is not in your system's PATH, or Python is not explicitly used to run it.

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.

gprof2dot: error: Graphviz's 'dot' tool not found.

The Graphviz `dot` command-line tool, which `gprof2dot` uses to render the graph, is not installed or not accessible in your system's PATH.

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.

gprof2dot: error: could not parse input as python profile data

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

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

gprof2dot: error: argument -f/--format: invalid choice: 'cprofile' (choose from 'callgrind', 'perf', 'python', 'hprof', 'oprofile', 'gprof')

An incorrect or unsupported profiler format name was provided to the `-f` or `--format` argument.

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.

Upgrade

Version history

2025.4.14latest on PyPI · released Apr 14, 2025

Audit

Dependencies

pythonrequiredRequires Python 3.8 or newer to run the script.

graphvizrequiredRequired externally to render the '.dot' graph files into images (e.g., PNG, SVG). Not installed by pip.

Agent activity

18 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/jrfonseca/gprof2dot ↗

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

homepagehttps://gprof2dot.jrf.org ↗