Registry / observability / pyprof2calltree

pyprof2calltree

JSON →
library1.4.5pypypi✓ verified 87d ago

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.

pip install pyprof2calltree
INSTALL
IMPORT
SIG · PYPROF2CALLTREE
P
pyprof2calltree
observabilitypythonv1.4.5
Install
2.4s avg
Import
89ms
Disk
17MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.4.5 · 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.103.910 runs
installs and imports cleanly · install 0.0s · import 0.095s · 19.2MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 2.4s · import 0.084s · 20MB
17MB installed
● package 17MB
Code
Verified usage

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

convert
from pyprof2calltree import convert
visualize
from pyprof2calltree import visualize

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
pyprof2calltree --version
Debug
Known issues
breakingOlder 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.
affects: >=1.4.4
gotchapyprof2calltree 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.
affects: *
deprecatedThe `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.
affects: >=1.4.5
Errors
Common errors & fixes
KCachegrind: 'Unknown File Format' error when opening a .prof or .pstat file.
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, ...
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.
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.
Upgrade
Version history
1.4.5latest on PyPI · released Apr 19, 2020
Audit
Dependencies
cProfilerequiredStandard Python profiling module whose output pyprof2calltree processes.
kcachegrindrequiredExternal graphical tool required to visualize the calltree output. QCachegrind is an alternative for Windows/macOS.
Agent activity
15 hits · last 30 days
node
12
OpenAI (training)
2
Amazon
1
Resources
pyprof2calltree — pip install pyprof2calltree · libregistry