objgraph: see what is holding your Python objects alive

One module, one file, no dependencies

objgraph lives in a single file, objgraph.py, at the root of the repository, and that is not a stylistic accident. It is a diagnostic tool that people tend to drop into a debugging session, so being able to grab one file and put it next to your script matters. The package still installs normally, with pip install objgraph or a download from PyPI, and the setup.py builds a package around that module with a name of objgraph and the author listed as Marius Gedminas. The repository layout is small and conventional for a single-module project: setup.py and setup.cfg for packaging, tests.py as the test module, a docs/ directory, a Makefile, a tox.ini, and a CHANGES.rst. The version number is not written in setup.py at all. Instead, get_version reads objgraph.py, matches a line of the form __version__ = and extracts it, so the module itself is the single source of truth for the version. That is a small detail, and it is the kind of thing that makes a one-file library pleasant to vendor.

The graph comes from Graphviz, and xdot makes it interactive

The drawing side is delegated entirely. The README states that you need Graphviz if you want to draw the pretty graphs, and it recommends xdot for interactive use, with pip install xdot being enough because objgraph will automatically look for it in your PATH. That recommendation is the difference between a static image and something you can explore. With xdot installed, the rendered graph is interactive, so you can click on a node and follow the reference chain rather than squinting at a PNG of a few hundred edges. The tool also degrades: you can work with the graph data without Graphviz present, you just do not get the picture. The Makefile shows how the images in the documentation are produced, through a setup.py --build-images target that runs the doctest suite from the docs directory and regenerates the graphs, and there is even an imgdiff target that compares the generated images against the committed ones, so a change in the rendering shows up in review as a picture difference.

It came out of a memory leak hunt, and the blog posts explain the design

The history section of the README explains the origin plainly. The author developed a set of functions that eventually became objgraph while hunting for memory leaks in a Python program, and the whole story with illustrated examples is in a series of blog posts: hunting memory leaks in Python, Python object graphs, and object graphs with Graphviz. That origin explains the design bias. objgraph is not trying to be a general profiler or a memory sampler. It is trying to answer one question, which is what is referencing this object. The documentation lives at mg.pov.lt/objgraph, and the project site is also the author's personal domain, which is a reasonable indicator of the scale of the tool. Bugs go to the GitHub issues page and the source is on GitHub, where it can be cloned with git clone https://github.com/mgedmin/objgraph.

Doctests are the test suite, which is unusual and sensible

The testing setup deserves a note because it says something about how the tool is meant to be trusted. setup.py contains a build_images function that imports the tests module, collects doctests through find_doctests, and runs them with doctest.DocFileSuite using doctest.ELLIPSIS and a custom IgnoreNodeCountChecker, so the expected output can ignore node counts rather than pinning an exact graph shape. The build fails with a non-zero exit if the doctests do not pass. That means the examples in the documentation are executable and verified, which for a tool whose output is a graph is the only practical way to test it: you cannot assert on a picture, so you assert on the doctest output around it. The tox.ini drives the same thing across environments, with make test running tox -p auto, make coverage running tox -e coverage, and make flake8 running tox -e flake8. A separate .coveragerc and the coveralls badge in the README show coverage is tracked.

Reading the graph means reading references, not sizes

This is where the value and the limit of the tool sit. A memory profiler tells you that a particular class accounts for a large share of allocated memory. That is a starting point, not an answer, because the interesting question is usually why those objects are still alive. objgraph works on the reference graph, so you start from an object and ask what refers to it, and the answer is the chain of references keeping it reachable. That chain is the thing that tells you which cache, which list or which closure is holding the structure. The trade-off is that this is a different question from the one profilers answer, and it requires you to already have a suspect object to start from. The library is not a sampler that finds problems on its own. It is an instrument you point at a specific place, which is why it lives in an interactive session or a debugging script rather than in a production pipeline.

Installation needs Graphviz on the machine, not just in the venv

Installing the Python package is the easy half:

pip install objgraph

The other half is system software. Graphviz has to be installed as a program, since the rendering happens through the dot tool rather than through a Python library, and the interactive experience depends on xdot:

pip install xdot

The README notes that objgraph will automatically look for xdot in your PATH, so there is no configuration step for it. On a workstation this is a minute of work. On a container, a CI image or a remote debugging host, it is the step that gets forgotten, and the symptom is that graphs do not render. There is also a documentation build path for contributors, with make docs running sphinx-build in HTML mode with warnings turned into errors via the -Wn option, and the target directory under docs/_build with a note to look at the built index afterwards. If you are evaluating this for a team, the practical question is whether the machines you will debug on have Graphviz available, because that determines whether the tool is usable there at all.

A two year gap, then a 3.7.0 release in October

The maintenance picture needs reading carefully. The repository is not archived and the last push was on 2026-10-16, and the 3.7.0 release carries the same timestamp, so the newest version is current. Before that, though, the listed releases are 3.6.2 and 3.6.1, both on 2024-10-10, minutes apart. That is a gap of close to two years between 3.6.2 and 3.7.0, so the project is not on a continuous release train and there is no regular schedule to plan around. For a debugging library the risk is low, since the API surface is small and stable, but it does mean that if you hit a bug you may be waiting a long time. The repository includes a CHANGES.rst with the history, and the README itself lists it as the place to see what has changed recently. The licence is MIT, with the LICENSE file at the root, and the project is packaged with setuptools through setup.py and setup.cfg, which is old school but entirely serviceable for a module this small.

Editorial conclusion

Adopt objgraph if you have a Python process whose memory you do not understand and you need to see which objects hold references to which others, especially when the usual size-based profiling tells you a type is heavy but not why it is retained. Do not adopt it as a general performance profiler or as a monitoring tool for production, since it is an interactive diagnostic that renders graphs through Graphviz. Before you commit, install Graphviz and xdot on the machine you will run it on, read the CHANGES.rst file in the repository, and check the 3.7.0 release notes, because the last push was on 2026-10-16 after a gap that started with the 3.6.2 release in 2024.

Frequently asked questions

Official sources

1. License: MIT
2. mgedmin/objgraph on GitHub
3. Project website
4. README
5. Releases