sphinx-gallery

What it is and what it does

Sphinx-Gallery is a Sphinx extension that transforms a directory of Python example scripts into an interactive HTML gallery embedded in your documentation. It executes each script, captures outputs (including plots from Matplotlib and related packages), and generates formatted gallery pages with the code, results, and narrative text from docstrings or accompanying README files.

You configure it in your Sphinx conf.py by specifying the source directory of example scripts and the output directory for generated gallery files. Sphinx-Gallery then handles execution, output capture, and reST file generation during your normal Sphinx build. It's designed for library documentation but can also serve as a standalone showcase for a Python package or module.

Use it for:

• Build an interactive example gallery for a scientific Python library (like scikit-learn or Matplotlib) to demonstrate typical usage patterns.
• Generate a gallery of tutorials or how-to guides from executable Python scripts as part of your project documentation.
• Showcase data analysis workflows or computational examples with live output and visualizations in a web-accessible format.
• Create a portfolio or cookbook of example code snippets with their results for educational or reference purposes.
• Automatically keep example outputs in sync with code changes by re-executing scripts during documentation builds.

Worth the install?

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

Sphinx-Gallery is a Sphinx extension that automatically generates HTML galleries of executable examples from Python scripts, extracting outputs and embedding them into your documentation.

Yes. Sphinx-Gallery is a mature, actively maintained tool with low install friction and no known vulnerabilities. It solves a concrete problem—turning Python scripts into documented, executable galleries—and is widely adopted by major projects. Install it if you need to showcase runnable examples in Sphinx documentation.

Install

sphinx-gallery on PyPI

pip install sphinx-gallery

uv add sphinx-gallery

poetry add sphinx-gallery

Installing sphinx-gallery

Before you install

Low friction: pure Python wheel with only two runtime dependencies (pillow and sphinx). Actively maintained as of 2026-04-24 with recent activity, supporting current Python versions (3.10–3.14).

License in practice

3-clause BSD is permissive; you can use, modify, and distribute sphinx-gallery freely in commercial and private projects with minimal restrictions.

Quickstart

pip install sphinx-gallery

# In doc/conf.py:
extensions = ['sphinx_gallery.gen_gallery']
sphinx_gallery_conf = {
    'examples_dirs': '../examples',
    'gallery_dirs': 'auto_examples',
}

Requires Sphinx and pillow as runtime dependencies; Python 3.10 or later.

Verify before relying

• Whether optional system binaries (optipng) are required or merely recommended for PNG optimization.
• Performance characteristics when processing large numbers of example scripts or high-resolution images.

Package facts

Evidence: sphinx_gallery-0.21.0-py3-none-any.whl

Tags

More Sphinx packages