Welcome to sphobjinv!

A toolkit for inspection/manipulation of Sphinx objects inventories

When documentation is built using, e.g., Sphinx’s StandaloneHTMLBuilder, an inventory of the named objects in the documentation set is dumped to a file called objects.inv in the html build directory. (One common location is, doc/build/html, though the exact location will vary depending on the details of how Sphinx is configured.) This file is read by intersphinx when generating links in other documentation.

Since version 1.0 of Sphinx (~July 2010), the data in these objects.inv inventories is compressed by zlib (presumably to reduce storage requirements and improve download speeds; “version 2”), whereas prior to that date the data was left uncompressed (“version 1”). This compression renders the files non-human-readable. It is the purpose of this package to enable quick and simple compression/decompression and inspection of these “version 2” inventory files.

In particular, sphobjinv was developed to satisfy two primary use cases:

  1. Searching and inspection of objects.inv contents in order to identify how to properly construct intersphinx references.

  2. Assembly of new objects.inv files in order to allow intersphinx cross-referencing of other documentation sets that were not created by Sphinx.

For more background on the mechanics of the Sphinx data model and Sphinx cross-references generally, see this talk from PyOhio 2019.


Install sphobjinv via pip:

$ pip install sphobjinv

Or, if you only plan to use the sphobjinv CLI, another option is pipx:

$ pipx install sphobjinv

As of Nov 2022, sphobjinv is also available via conda-forge. After activating the desired conda environment:

$ conda install -c conda-forge sphobjinv

Alternatively, sphobjinv is packaged with multiple POSIX distributions and package managers, including:

  • Alpine Linux: py3-sphobjinv (info)

  • Arch Linux: python-sphobjinv (info)

  • Fedora: python-sphobjinv (info)

  • Gentoo: dev-python/sphobjinv (info)

  • Guix: python-sphobjinv

  • Manjaro: python-sphobjinv

  • OpenEuler: python-sphobjinv

  • openSUSE: python-sphobjinv (info)

  • Parabola: python-sphobjinv (info)

  • pkgsrc: textproc/py-sphobjinv (info)

  • spack: py-sphobjinv (info)

sphobjinv is configured for use both as a command-line script and as a Python package.

The optional dependency python-Levenshtein for accelerating the “suggest” functionality is no longer available due to a licensing conflict, and has been deprecated. See here for more information.

The project source repository is on GitHub: bskinn/sphobjinv.

Indices and Tables

IndexModule IndexSearch Page