sphinxcontrib-images

What it is and what it does

sphinxcontrib-images is a Sphinx extension that enhances HTML documentation by replacing standard image directives with thumbnail previews and lightbox zoom functionality. It lets you display smaller preview images in your docs that expand when clicked, improving page load time and visual organization. The extension depends on Sphinx and requests, and works by intercepting the image directive during documentation builds.

The package supports grouping images, downloading and caching remote images, and provides fallback rendering for non-HTML formats like LaTeX and EPUB. It is designed to be extensible—you can add custom HTML preview solutions or preprocess images by writing a few lines of code. However, the TODO list notes that proper image scaling (thumbnail generation) is not yet implemented, so it currently shows full-size images in a thumbnail container rather than creating actual scaled versions.

Use it for:

• Reduce HTML documentation page load time by showing image thumbnails instead of full-resolution images
• Add interactive lightbox zoom to image galleries in Sphinx-generated documentation
• Group related images in documentation with automatic preview and enlargement on click
• Cache remote images locally during documentation builds to avoid external dependencies
• Extend the extension with custom preview backends or image preprocessing pipelines

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A Sphinx extension that replaces standard image directives with thumbnails and lightbox zoom functionality for HTML documentation output.

Yes, if you are building HTML documentation with Sphinx and want thumbnail and lightbox functionality without heavy setup. The low install friction and permissive license make it a reasonable choice. However, be aware that the project is aging (433 days since last release) and core features like actual image scaling are still TODO; verify that the current state meets your needs before committing to it in production documentation pipelines.

Install

sphinxcontrib-images on PyPI

pip install sphinxcontrib-images

uv add sphinxcontrib-images

poetry add sphinxcontrib-images

Installing sphinxcontrib-images

Before you install

Low friction install with only requests and sphinx as runtime dependencies. Maintenance status is aging—last release was 433 days ago, though the repository remains active with a recent commit on 2025-07-29.

License in practice

Licensed under Apache-2.0 (permissive), allowing use in commercial and open-source projects with minimal restrictions.

Quickstart

pip install sphinxcontrib-images

Then add to conf.py:
extensions = ['sphinxcontrib.images']

In your .rst file:
.. thumbnail:: picture.png

Requires Python 3.9 or later; thumbnail generation (image scaling) is listed as a TODO and not yet implemented.

Verify before relying

• Whether remote image caching actually works or is still in development
• Current state of non-HTML output support (latex, epub fallback behavior)
• Whether LightBox2 integration is fully functional or has known limitations
• How actively the extension is maintained given 433 days since last release

Package facts

Evidence: sphinxcontrib_images-1.0.1-py3-none-any.whl

Tags

More Documentation packages