gprof2dot

Warnings

• gotcha 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.
  Fix: Install Graphviz separately and ensure its `dot` executable is in your system's PATH.
• breaking 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.
  Fix: Ensure you are running gprof2dot with Python 3.8 or a later version.
• gotcha 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`.
  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.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Users should be aware of the project's maintenance status and manage expectations for new features or rapid bug fixes.

Install

• pip install gprof2dot Install with pip

Imports

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

Quickstart

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)