Guppy 3 (Guppy-PE for Python 3)

3.1.6 · active · verified Sat Apr 11

Guppy 3 is a comprehensive Python programming environment and heap analysis toolset, primarily serving as a port of the original Guppy-PE (Guppy-Python Environment) from Python 2 to Python 3. It provides robust tools for object and heap memory sizing, profiling, and analysis, essential for debugging memory-related issues and optimizing Python program performance. The library consists of subpackages like `heapy` for detailed heap introspection, `gsl` for a specification language, and `sets` for C-implemented bitsets and nodesets. The project maintains an active development status with regular minor releases.

Warnings

gotcha Python Version Incompatibility: Guppy3 currently requires Python 3.10-3.14. Using it with unsupported Python versions (e.g., older 3.x versions like 3.9 or earlier, or Python 2) will lead to installation failures or runtime errors.
Fix: Ensure your environment uses Python 3.10, 3.11, 3.12, 3.13, or 3.14. Check `guppy3` PyPI page for the latest `Requires-Python` metadata.
gotcha CPython Exclusive & Free-threaded CPython Not Supported: Guppy3 is strictly for CPython and does not work with other Python implementations (like PyPy). Additionally, it currently lacks support for future free-threaded CPython versions due to internal complexities.
Fix: Only use `guppy3` with standard CPython interpreters. Avoid using it in environments that implement or enable free-threading.
gotcha Tkinter Dependency for Graphical Browser: The interactive graphical heap profiler requires the `Tkinter` library, which is not always included with Python installations. Attempting to use GUI features without it will fail.
Fix: Install `Tkinter` (e.g., `sudo apt-get install python3-tk` on Debian/Ubuntu, or ensure your Python distribution includes it).
gotcha Potential TensorFlow Incompatibility: Users have reported that `h.heap()` calls might terminate without explicit errors when used within applications that extensively use TensorFlow, suggesting possible underlying conflicts.
Fix: If experiencing silent termination, try isolating `guppy3` usage from TensorFlow operations or investigate specific interaction points. Consider alternative memory profilers if direct integration causes issues.
gotcha Historical Windows Crash with pywin32: Older `guppy3` versions on Windows could crash if `pywin32` was below version 300. While likely resolved with current `pywin32` releases, this could still be a factor in older or specific Windows setups.
Fix: Ensure `pywin32` is updated to the latest version (`pip install -U pywin32`) if encountering stability issues on Windows.

Install

pip install guppy3 Install with pip
conda install -c conda-forge guppy3 Install with conda

Imports

hpy
```
from guppy import hpy
```
The `hpy` object is the primary entry point to `heapy` functionality.

Quickstart

This example demonstrates how to initialize the `heapy` profiler, set a reference point, allocate some objects, and then take a heap snapshot to analyze memory usage. It also shows how to isolate specific objects for inspection.

from guppy import hpy

def create_some_objects():
    a = [1, 2, 3] * 1000
    b = {'x': 1, 'y': 2} * 500
    return a, b

h = hpy() # Create a Heapy session context
h.setref() # Set a reference point for memory tracking

# Perform some operations that allocate memory
obj_a, obj_b = create_some_objects()

# Get a heap snapshot of newly allocated objects since setref()
heap_snapshot = h.heap()

print("Memory usage snapshot:")
print(heap_snapshot)

# To view the shortest paths to the single largest object (if any):
# if heap_snapshot.byid:
#     print("\nShortest path to largest object:")
#     print(heap_snapshot.byid[0].sp)

# Example of isolating objects
h_iso = h.iso(obj_a, obj_b)
print("\nIsolated objects snapshot:")
print(h_iso)

# You can also run internal tests to verify installation:
# h.test()

view raw JSON →