Using the extension

Install the package and enable it in conf.py:

extensions = [
    "sphinx_numref_performance",
]

Then build the documentation as usual:

sphinx-build -M html docs docs/_build

There is nothing to configure. Every builder benefits, because references are resolved before a builder writes anything.

What changes

Build time. Sphinx’s own resolver still formats each reference, so the following are unchanged:

  • figure, table, code block, and section numbers

  • reference titles, including numfig_format and explicit :numref:`Table {number} <label> titles

  • every warning, such as numfig is disabled. :numref: is ignored., the link has no caption, and Any number is not assigned

The test suite builds a project with and without the extension and asserts that the HTML and LaTeX output, and the warnings, are identical.

Rebuilds

The extension records what it needs while each document is read, and keeps it in the build environment. Enabling or removing the extension therefore makes Sphinx read every document once more, after which incremental rebuilds behave normally.

Compatibility

Sphinx 8.1 through 9.x, on Python 3.10 and later. Parallel reads (sphinx-build -j) are supported; the collected data is merged from the worker processes the same way Sphinx merges its own.

Leaving the extension enabled on a Sphinx release that already contains the upstream fix is harmless. It costs nothing measurable, and its resolution path produces the same result. Removing it is still the right move once the fix is released.