---
id: guppy3
version: "3.1.7"
license: MIT
license_treatment: permissive
maintenance: active
---

# guppy3 — Guppy 3 -- Guppy-PE ported to Python 3

License: permissive · Maintenance: active · Downloads: 1.4M/mo

## What it is and what it does

Guppy 3 is a heap analysis and memory profiling toolkit for CPython that lets you inspect live Python objects, understand memory allocation patterns, and track down memory leaks. It provides an interactive session interface where you create a heap analysis context, query the heap to see object counts and sizes grouped by type, and trace paths from the root to individual objects. The package includes submodules for bitsets implemented in C, a specification language, and support utilities.

The tool is designed for developers debugging memory issues in Python applications. It works by examining the live heap state and presenting partitions of objects with cumulative size analysis, making it practical for identifying which types consume the most memory. It requires CPython 3.10 or later and does not support PyPy or free-threaded CPython due to implementation constraints.

Use it for:

- Identify which object types consume the most memory in a running Python application.
- Trace reference chains from the garbage collector root to specific large objects.
- Profile memory usage in long-running services to detect unexpected growth patterns.
- Debug memory issues in framework-based applications by inspecting heap state at runtime.
- Analyze object allocation patterns during development to optimize memory-intensive code.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Guppy 3 analyzes Python heap memory to identify object allocations, memory usage patterns, and potential leaks through interactive heap inspection and reporting.

Yes, if you need to debug Python memory issues or profile heap usage in CPython applications. The package is actively maintained, has no known vulnerabilities, and carries a permissive MIT license. Install friction is moderate due to compiled extensions, but pre-built wheels cover common platforms. Not suitable if you use PyPy, free-threaded CPython, or Python versions below 3.10.

## Install

pip install guppy3
uv add guppy3
poetry add guppy3

## Installing guppy3

Before you install: Medium install friction due to compiled C extensions across multiple platforms and architectures. The package is actively maintained with a recent release (95 days ago) and receives steady downloads, though it requires CPython 3.10 or later and does not support PyPy or free-threaded CPython.

License in practice: MIT license permits free use, modification, and redistribution with minimal restrictions, making it suitable for both open-source and commercial projects.

Quickstart:

pip install guppy3

from guppy import hpy
h = hpy()
h.heap()
h.iso(1, [], {})

Requires CPython 3.10, 3.11, 3.12, 3.13, or 3.14; PyPy and free-threaded CPython are not supported. Tkinter is needed for the graphical browser.

Verify before relying:

- Whether the graphical browser is actively used or primarily a legacy feature
- Performance overhead and suitability for production vs. development-only use
- Practical memory profiling workflow and typical use patterns in real applications

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 1.4M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

python memory profiling, heap analysis tool, memory leak detection, object allocation tracking, python memory debugging, heap introspection, memory usage analysis, memory-profiling, heap-analysis, debugging

[View on SkillFed](https://skillfed.io/packages/guppy3) · [View on PyPI](https://pypi.org/project/guppy3/)