pyprof2calltree

1.4.5 · active · verified Thu Apr 16

pyprof2calltree is a Python utility that facilitates the visualization of profiling data collected with Python's standard `cProfile` module. It converts `cProfile` output into the calltree format, which can then be graphically analyzed using tools like KCachegrind or QCachegrind. The library, currently at version 1.4.5, is actively maintained with updates primarily focusing on Python version compatibility and minor improvements.

Common errors

```
KCachegrind: 'Unknown File Format' error when opening a .prof or .pstat file.
```
cause KCachegrind cannot directly read the raw output from Python's `cProfile` module. It requires data in the `callgrind` format.

fix Always convert `cProfile` output files (e.g., `my_app.prof`) into the `callgrind` format using `pyprof2calltree` first: `pyprof2calltree -i my_app.prof -o callgrind.out`. Then open `callgrind.out` in KCachegrind.
```
Could not find kcachegrind. Tried: /usr/bin/kcachegrind, /usr/local/bin/kcachegrind, ...
```
cause The `kcachegrind` (or `qcachegrind`) executable is not installed on your system or is not located in any directory listed in your system's PATH environment variable.

fix Ensure KCachegrind or QCachegrind is installed and its executable path is included in your system's PATH. On Linux, `sudo apt install kcachegrind` or equivalent is common. On macOS, `brew install qcachegrind` is often used.
```
Profiling data in KCachegrind appears confusing, or a 'fast' function shows high 'Incl.' (Inclusive) time.
```
cause Misinterpretation of KCachegrind's 'Self' (tottime) and 'Incl.' (cumtime) metrics. 'Incl.' time includes time spent in child calls, while 'Self' time is exclusive to the function itself.

fix When analyzing performance, 'Self' time (or 'tottime' in `cProfile`) often indicates where the function *itself* is spending time, making it crucial for identifying bottlenecks within that specific function's code. 'Incl.' time (or 'cumtime') shows the total time spent in a function *and all its children*, which is useful for understanding the overall cost of a call path. Focus on functions with high 'Self' time for direct optimization within that function.

Warnings

breaking Older Python versions are no longer officially supported. Version 1.4.4 dropped official support for Python 2.5, 2.6, 3.2, and 3.3. Ensure you are using a compatible Python version (3.4+).
Fix: Upgrade to a supported Python version (e.g., Python 3.7+ for latest releases) if encountering compatibility issues.
gotcha pyprof2calltree only *converts* profiling data. You must separately install a visualization tool like `kcachegrind` (Linux) or `qcachegrind` (Windows/macOS) to view the generated `.kgrind` or `.out` files.
Fix: Install KCachegrind (e.g., `sudo apt install kcachegrind` on Debian/Ubuntu, `brew install qcachegrind` on macOS) or QCachegrind for your operating system.
deprecated The `eggsecutable` script for running `pyprof2calltree` was removed in v1.4.5. Rely on `pip install` and the `pyprof2calltree` command-line entry point or direct library imports.
Fix: Use `python -m pyprof2calltree` or the installed `pyprof2calltree` command-line script instead of older `eggsecutable` methods.

Install

pip install pyprof2calltree Install with pip
sudo apt install kcachegrind pyprof2calltree Install on Debian/Ubuntu (includes kcachegrind)

Imports

convert
```
from pyprof2calltree import convert
```
visualize
```
from pyprof2calltree import visualize
```

Quickstart

This quickstart demonstrates how to profile a Python function using `cProfile`, then convert the profiling data to the KCachegrind-compatible calltree format using `pyprof2calltree.convert`. The resulting file can be opened with KCachegrind or QCachegrind for interactive visualization. An alternative `visualize()` function can attempt to launch KCachegrind directly if it's in your system's PATH.

import cProfile
import os
from pyprof2calltree import convert, visualize

def my_expensive_function():
    total = 0
    for i in range(1_000_000):
        total += i * i
    return total

def main_app_logic():
    _ = my_expensive_function()
    return "Done profiling."

profiler = cProfile.Profile()
profiler.enable()
main_app_logic()
profiler.disable()

# Option 1: Save to a file for later viewing
output_filename = 'profiling_results.kgrind'
with open(output_filename, 'w') as f:
    convert(profiler.getstats(), f)
print(f"Profiling data saved to {output_filename}. Open with kcachegrind {output_filename}")

# Option 2: Directly visualize (requires kcachegrind in PATH)
# try:
#     visualize(profiler.getstats())
#     print("KCachegrind launched with profiling data.")
# except Exception as e:
#     print(f"Could not launch KCachegrind directly: {e}. Ensure it's installed and in your PATH.")

# Example of running a script directly and converting via command line:
# 1. python -m cProfile -o my_app.prof your_script.py
# 2. pyprof2calltree -i my_app.prof -o callgrind.out

view raw JSON →