{"id":3508,"library":"guppy3","title":"Guppy 3 (Guppy-PE for Python 3)","description":"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.","status":"active","version":"3.1.6","language":"en","source_language":"en","source_url":"https://github.com/zhuyifei1999/guppy3/","tags":["memory profiling","heap analysis","debugging","performance","memory leak detection"],"install":[{"cmd":"pip install guppy3","lang":"bash","label":"Install with pip"},{"cmd":"conda install -c conda-forge guppy3","lang":"bash","label":"Install with conda"}],"dependencies":[{"reason":"Requires Python 3.10, 3.11, 3.12, 3.13, or 3.14. Older guppy3 versions supported 3.7+.","package":"python","optional":false},{"reason":"This package is CPython only; PyPy and other Python implementations are not supported.","package":"CPython","optional":false},{"reason":"Required to use the graphical heap profile browser.","package":"Tkinter","optional":true}],"imports":[{"note":"The `hpy` object is the primary entry point to `heapy` functionality.","symbol":"hpy","correct":"from guppy import hpy"}],"quickstart":{"code":"from guppy import hpy\n\ndef create_some_objects():\n    a = [1, 2, 3] * 1000\n    b = {'x': 1, 'y': 2} * 500\n    return a, b\n\nh = hpy() # Create a Heapy session context\nh.setref() # Set a reference point for memory tracking\n\n# Perform some operations that allocate memory\nobj_a, obj_b = create_some_objects()\n\n# Get a heap snapshot of newly allocated objects since setref()\nheap_snapshot = h.heap()\n\nprint(\"Memory usage snapshot:\")\nprint(heap_snapshot)\n\n# To view the shortest paths to the single largest object (if any):\n# if heap_snapshot.byid:\n#     print(\"\\nShortest path to largest object:\")\n#     print(heap_snapshot.byid[0].sp)\n\n# Example of isolating objects\nh_iso = h.iso(obj_a, obj_b)\nprint(\"\\nIsolated objects snapshot:\")\nprint(h_iso)\n\n# You can also run internal tests to verify installation:\n# h.test()","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"<3.10"},{"fix":"Only use `guppy3` with standard CPython interpreters. Avoid using it in environments that implement or enable free-threading.","message":"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.","severity":"gotcha","affected_versions":"All versions on non-CPython interpreters; future free-threaded CPython versions"},{"fix":"Install `Tkinter` (e.g., `sudo apt-get install python3-tk` on Debian/Ubuntu, or ensure your Python distribution includes it).","message":"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.","severity":"gotcha","affected_versions":"All versions using GUI features"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions, when used with TensorFlow"},{"fix":"Ensure `pywin32` is updated to the latest version (`pip install -U pywin32`) if encountering stability issues on Windows.","message":"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.","severity":"gotcha","affected_versions":"Older versions on Windows with pywin32 < 300"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}