Skip to main content
Donate to the Python Software Foundation or Purchase a PyCharm License to Benefit the PSF! Donate Now

Draws Python object reference graphs with graphviz

Project description

Python Object Graphs

objgraph is a module that lets you visually explore Python object graphs.

You’ll need graphviz if you want to draw the pretty graphs.

I recommend xdot for interactive use. pip install xdot should suffice; objgraph will automatically look for it in your PATH.

Installation and Documentation

pip install objgraph or download it from PyPI.

Documentation lives at


I’ve developed a set of functions that eventually became objgraph when I was hunting for memory leaks in a Python program. The whole story – with illustrated examples – is in this series of blog posts:

Support and Development

The source code can be found in this Bazaar repository:

To check it out, use bzr branch lp:objgraph.

Report bugs at


1.7.1 (2011-12-11)

  • Bugfix: non-ASCII characters in object representations would break graph generation on Python 3.x, in some locales (e.g. with LC_ALL=C). Reported and fixed by Stefano Rivera.
  • Bugfix: was broken on Python 3.x
  • Bugfix: dot.exe/xdot.exe were not found on Windows (LP#767239).
  • Documentation updates: document the forgotten find_ref_chain, update show_chain prototype.

1.7.0 (2011-03-11)

  • New function: find_ref_chain.
  • New backrefs argument for show_chain.
  • New function: get_leaking_objects, based on a blog post by Kristjan Valur.
  • New objects argument for count, typestats, most_common_types, show_most_common_types, and by_type.
  • Edges pointing to function attributes such as __defaults__ or __globals__ are now labeled.
  • Edge labels that are not simple strings now show the type.
  • Bugfix: ‘0’ and other unsafe characters used in a dictionary key could break graph generation.
  • Bugfix: show_refs(…, filename=’’) would then go to complain about unrecognized file types and then produce a png.

1.6.0 (2010-12-18)

  • Python 3 support, thanks to Stefano Rivera (fixes LP#687601).
  • Removed weird weakref special-casing.

1.5.1 (2010-12-09)

  • Avoid test failures in uncollectable-garbage.txt (fixes LP#686731).
  • Added HACKING.txt.

1.5.0 (2010-12-05)

  • Show frame objects as well (fixes LP#361704).
  • New functions: show_growth, show_chain.
  • find_backref_chain returns [obj] instead of None when a chain could not be found. This makes show_chain(find_backref_chain(...), ...) not break.
  • Show how many references were skipped from the output of show_refs/show_backrefs by specifying too_many.
  • Make show_refs descend into modules.
  • Do not highlight classes that define a __del__, highlight only instances of those classes.
  • Option to show reference counts in show_refs/show_backrefs.
  • Add Sphinx documentation and a PyPI long description.

1.4.0 (2010-11-03)

  • Compatibility with Python 2.4 and 2.5 (tempfile.NamedTemporaryFile has no delete argument).
  • New function: most_common_types.

1.3.1 (2010-07-17)

  • Rebuild an sdist with no missing files (fixes LP#606604).
  • Added and a Makefile to check that sdist generates source distributions with no files missing.

1.3 (2010-07-13)

  • Highlight objects with a __del__ method.
  • Fixes LP#483411: suggest always passing [obj] to show_refs, show_backrefs, since obj might be a list/tuple.
  • Fixes LP#514422: show_refs, show_backrefs don’t create files in the current working directory any more. Instead they accept a filename argument, which can be a .dot file or a .png file. If None or not specified, those functions will try to spawn xdot as before.
  • New extra_info argument to graph-generating functions (patch by Thouis Jones, LP#558914).
  • should work with distutils now (LP#604430, thanks to Randy Heydon).

1.2 (2009-03-25)

  • Project website, public source repository, uploaded to PyPI.
  • No code changes.

1.1 (2008-09-10)

  • New function: show_refs for showing forward references.
  • New functions: typestats and show_most_common_types.
  • Object boxes are less crammed with useless information (such as IDs).
  • Spawns xdot if it is available.

1.0 (2008-06-14)

  • First public release.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
objgraph-1.7.1.tar.gz (546.2 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page