---
id: sphinxcontrib-images
version: "1.0.1"
license: Apache-2.0
license_treatment: permissive
maintenance: aging
---

# sphinxcontrib-images — Sphinx extension for thumbnails

License: permissive · Maintenance: aging · Downloads: 86.6K/mo

## 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 above — 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

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

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 86.6K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

sphinx thumbnail extension, sphinx image lightbox, sphinx documentation thumbnails, sphinx fancybox images, sphinx html image preview, sphinx-extension, documentation-tooling

[View on SkillFed](https://skillfed.io/packages/sphinxcontrib-images) · [View on PyPI](https://pypi.org/project/sphinxcontrib-images/)