Install & Compatibility
Where this runs
tested against v3.6.2 · 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
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.083s · 18.3MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.6s · import 0.072s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
objgraph
✓ import objgraph
The primary module containing all functions.
This quickstart demonstrates how to create some interconnected Python objects and then use `objgraph.show_refs` to visualize objects reachable from a given object, `objgraph.show_backrefs` to see what objects reference a specific object, and `objgraph.show_most_common_types` to get a summary of memory usage. For graph visualization, ensure the Graphviz system utility is installed and accessible in your PATH.
import objgraph
def create_objects():
x = []
y = [x, [x], {'x_key': x}]
z = {'list_ref': y, 'dict_ref': {'inner_x': x}}
return x, y, z
x, y, z = create_objects()
# Show references reachable from 'y', save to a PNG
objgraph.show_refs([y], filename='sample-graph.png', max_depth=2)
print("Generated sample-graph.png showing references from 'y'")
# Show backreferences to 'x', save to a PNG
objgraph.show_backrefs([x], filename='sample-backref-graph.png', max_depth=2)
print("Generated sample-backref-graph.png showing backreferences to 'x'")
# Show most common types in memory
print("\nMost common types in memory:")
objgraph.show_most_common_types(limit=5)
objgraph --version
Debug
Known issues
breakingobjgraph version 3.6.0 and later dropped support for Python 2.x and Python 3.7. Previous versions (e.g., 3.5.0) dropped Python 3.5 support, and 3.4.1 dropped 3.3 and 3.4.fixEnsure your Python environment is 3.8 or newer for `objgraph>=3.6.0`. Check `objgraph`'s `requires_python` metadata on PyPI for the exact minimum version supported by your target `objgraph` version.
affects: >=3.6.0 (for Python 2.x, 3.7); >=3.5.0 (for Python 3.5); >=3.4.1 (for Python 3.3, 3.4)
gotchaDrawing object graphs with `show_refs()` or `show_backrefs()` requires the external Graphviz system utility to be installed and available in your system's PATH. Without it, image generation will fail.fixInstall Graphviz on your operating system (e.g., `sudo apt-get install graphviz` on Debian/Ubuntu, `brew install graphviz` on macOS, or download from graphviz.org). Optionally, install the Python `graphviz` package (`pip install graphviz` or `pip install objgraph[ipython]`) for better integration, especially in Jupyter.
affects: All versions
gotchaIn IPython/Jupyter notebooks, before version 3.5.0, explicitly passing a `filename` argument to `show_refs()` or `show_backrefs()` might still trigger inline graph display instead of only saving to the specified file.fixUpgrade to objgraph 3.5.0 or later to ensure the `filename` argument behaves as expected, or omit `filename` to leverage the interactive viewer if `xdot` is installed.
affects: <3.5.0
gotchaFor interactive viewing of graphs without saving to a file, `objgraph` can integrate with `xdot`. You'll need to install `xdot` separately (`pip install xdot` or system-wide) and omit the `filename` argument from `show_refs`/`show_backrefs`.fixInstall `xdot` (`pip install xdot` or via system package manager) and call `show_refs()` or `show_backrefs()` without a `filename` argument.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'objgraph'
The 'objgraph' package is not installed in the current Python environment or the Python interpreter being used by your IDE/terminal does not have access to it.
fixEnsure objgraph is installed by running: `pip install objgraph` or `pip3 install objgraph`. If using a virtual environment, activate it first. If in an IDE, ensure the correct Python interpreter is selected.
Image renderer (dot) not found, not doing anything else.
objgraph relies on the external Graphviz software to render object graphs into image files (like PNGs) or display them interactively. This error indicates that the 'dot' executable (part of Graphviz) is not installed on your system or is not accessible in your system's PATH.
fixInstall Graphviz on your operating system and ensure its executables (especially `dot`) are added to your system's PATH. For example, on Ubuntu: `sudo apt-get install graphviz`, on macOS with Homebrew: `brew install graphviz`, or download from graphviz.org for Windows.
ERROR: Could not find a version that satisfies the requirement objgraph
This error typically occurs when your Python version does not meet the requirements of the latest objgraph release, or your pip version is outdated, preventing it from finding compatible package versions.
fixUpgrade pip to its latest version: `python -m pip install --upgrade pip`. Also, verify that your Python version is compatible with objgraph (objgraph requires Python >= 3.7). If not, update your Python installation.
graphviz.backend.ExecutableNotFound: failed to execute ['dot', '-V'], make sure the Graphviz executables are on your systems' PATH
objgraph relies on the external Graphviz command-line tools to render graphs, but the 'dot' executable is not found in your system's PATH.
fixInstall Graphviz on your operating system (e.g., `sudo apt-get install graphviz` on Debian/Ubuntu, `brew install graphviz` on macOS, or download from graphviz.org) and ensure its executables are added to your system's PATH environment variable.
ImportError: You need to install pygraphviz or graphviz for Graphviz support.
objgraph requires a Python wrapper for Graphviz (either pygraphviz or graphviz) to be installed to interact with the Graphviz executables, but neither was found.
fixInstall one of the Python Graphviz wrapper libraries: `pip install graphviz` (recommended) or `pip install pygraphviz`
Upgrade
Version history
3.6.2latest on PyPI · released Oct 10, 2024
Audit
Dependencies
graphviz (system utility)requiredRequired for generating and rendering DOT graph files into images (e.g., PNG) or for interactive viewing with tools like xdot.
graphviz (Python package)optionalOptional Python binding for Graphviz, used for inline display in environments like IPython/Jupyter notebooks. Included with `objgraph[ipython]` installation.