guppy3

library3.1.7pypypi✓ verified 22d ago

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.

observability

pip install guppy3

github ↗package ↗

INSTALL

IMPORT

SIG · GUPPY3

guppy3

observabilitypythonv3.1.7

Install

2.0s avg

Import

—

Disk

19MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.1.7 · 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.000s · 20.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.0s · import 0.000s · 22MB

19MB installed

● package 19MB

Code

Verified usage

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

hpy

✓ from guppy import hpy

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

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

guppy --version

Debug

Known issues

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

affects: <3.10

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

affects: All versions on non-CPython interpreters; future free-threaded CPython versions

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

affects: All versions using GUI features

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

affects: All versions, when used with TensorFlow

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

affects: Older versions on Windows with pywin32 < 300

Errors

Common errors & fixes

ImportError: cannot import name 'hpy' from 'guppy'

Developers often try to import `hpy` directly from the top-level `guppy` package after installing `guppy3`, but `hpy` is part of the `guppy.heapy` subpackage and is exposed via `guppy`'s `__init__.py`.

fix

Ensure you are using `from guppy import hpy` after installing `guppy3`, and that no other `guppy` installations or conflicting packages are present. The `hpy()` function is exposed directly by the `guppy` package. If this exact error occurs, it often means the `guppy3` package itself might be corrupted or an older `guppy` (Python 2) package is interfering. Reinstalling `guppy3` in a clean environment is a good first step.

error: command 'gcc' failed with exit status 1

Guppy3 includes C extensions that require a C compiler (like GCC) and Python development headers to be installed on your system during the `pip install` process. This error indicates that these prerequisites are missing.

fix

On Debian/Ubuntu, install `build-essential` and `python3-dev` (or `python-dev` for Python 2, though `guppy3` is for Python 3): `sudo apt-get update && sudo apt-get install build-essential python3-dev`. On Fedora/RHEL, use `sudo dnf install @development-tools python3-devel`. On macOS, install Xcode Command Line Tools: `xcode-select --install`. Ensure your environment variables are correctly set for the compiler.

ImportError: Error relocating /path/to/guppy/heapy/heapyc.cpython-XYZ.so: malloc_stats: symbol not found

This specific `ImportError` occurs when `guppy3`'s C extensions are compiled against a `glibc`-based system (like most standard Linux distributions) but then run on a system using `musl` libc (common in Alpine Linux or specific Docker images), where the `malloc_stats` symbol is not available.

fix

You need to compile `guppy3` in the target `musl` environment itself, or use a pre-built wheel that is compatible with `musl`. If using Docker, ensure your build stage for installing `guppy3` uses an Alpine-based image that has development tools installed (`apk add build-base python3-dev`) to compile it directly, or switch to a `glibc`-based image (e.g., Debian or Ubuntu). For example, `RUN apk add build-base python3-dev && pip install guppy3`.

Application crash or segmentation fault when calling hpy().heap() on Windows

On Windows, older versions of `pywin32` (specifically those less than 300) can cause a NULL pointer dereference, leading to a crash or segmentation fault when `guppy3` attempts to generate a referrer graph using `h.heap()`.

fix

Upgrade your `pywin32` package to version 300 or newer: `pip install -U pywin32`. If the issue persists, ensure all other dependencies are up to date and consider testing in a fresh virtual environment.

Upgrade

Version history

3.1.7latest on PyPI · released May 11, 2026

Audit

Dependencies

pythonrequiredRequires Python 3.10, 3.11, 3.12, 3.13, or 3.14. Older guppy3 versions supported 3.7+.

CPythonrequiredThis package is CPython only; PyPy and other Python implementations are not supported.

TkinteroptionalRequired to use the graphical heap profile browser.

Agent activity

17 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/zhuyifei1999/guppy3 ↗

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