---
id: sphinx-gallery
version: "0.21.0"
license: 3-clause BSD
license_treatment: permissive
maintenance: active
---

# sphinx-gallery — A Sphinx extension that builds an HTML gallery of examples from any set of Python scripts.

License: permissive · Maintenance: active · Downloads: 650.8K/mo

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

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

- License: 3-clause BSD (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 650.8K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

sphinx documentation gallery generator, python example gallery builder, sphinx extension example showcase, auto-generate documentation examples, executable python script gallery, sphinx gallery from python files, documentation example runner, documentation-generation, sphinx-extension, example-gallery

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