{"id":5063,"library":"sphinx-gallery","title":"Sphinx-Gallery","description":"Sphinx-Gallery is a Sphinx extension that automatically generates an HTML gallery of examples from any set of Python scripts. It converts `.py` files into reStructuredText, Jupyter notebooks, and includes features like thumbnail generation and API back-references. It is actively maintained with frequent releases, currently at version 0.20.0.","status":"active","version":"0.20.0","language":"en","source_language":"en","source_url":"https://github.com/sphinx-gallery/sphinx-gallery","tags":["documentation","sphinx","gallery","examples","code-gallery","jupyter"],"install":[{"cmd":"pip install sphinx-gallery","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Added as a dependency in v0.15.0 for image processing; essential for thumbnail generation and image scraping.","package":"Pillow","optional":false}],"imports":[{"note":"Sphinx-Gallery is typically enabled by adding its module path to the 'extensions' list in Sphinx's `conf.py` file, rather than importing specific symbols for direct use within `conf.py`.","symbol":"sphinx_gallery.gen_gallery","correct":"extensions = ['sphinx_gallery.gen_gallery']"}],"quickstart":{"code":"import os\n\n# conf.py example\nextensions = [\n    # ... other extensions\n    'sphinx_gallery.gen_gallery',\n]\n\n# Path to the directory containing example scripts, relative to conf.py\nexamples_dir = os.path.join(os.path.dirname(__file__), '../examples')\n\n# Path to where Sphinx-Gallery should save its generated output, relative to conf.py\ngallery_dir = 'auto_examples'\n\nsphinx_gallery_conf = {\n    'examples_dirs': examples_dir,\n    'gallery_dirs': gallery_dir,\n    'plot_gallery': 'True', # Set to False to disable example execution\n    'backreferences_dir': 'gen_modules/backreferences' # For mini-galleries\n}\n","lang":"python","description":"To integrate Sphinx-Gallery, first enable it by adding `'sphinx_gallery.gen_gallery'` to the `extensions` list in your Sphinx `conf.py` file. Then, define the `sphinx_gallery_conf` dictionary to specify the input directory for your example scripts (`examples_dirs`) and the output directory for the generated gallery (`gallery_dirs`). The paths should be relative to `conf.py`."},"warnings":[{"fix":"Upgrade your Python environment to version 3.10 or newer. If you need Python 3.8 support, use sphinx-gallery<0.20.0.","message":"Support for Python 3.8 has been dropped. Sphinx-Gallery now requires Python >=3.10.","severity":"breaking","affected_versions":">=0.20.0"},{"fix":"Ensure your environment uses Python 3.9+ and Sphinx 5+. If upgrading Sphinx is not an option, use sphinx-gallery<0.17.0.","message":"Support for Python 3.8 and Sphinx 4 has been dropped. Sphinx-Gallery now requires Python >=3.9 and Sphinx >=5.","severity":"breaking","affected_versions":">=0.17.0"},{"fix":"Update your `conf.py` to pass string references for these configuration options instead of direct callable objects.","message":"Due to Sphinx 7.3.0+ caching changes, certain `sphinx_gallery_conf` options that accept callables (e.g., `reset_argv`, `FileNameSortKey`, `notebook_modification_function`) must now be provided as fully qualified name *strings* (e.g., `'path.to.my_function'`) instead of instantiated classes or direct callables. Passing objects with unstable `__repr__` can force unnecessary rebuilds.","severity":"breaking","affected_versions":">=0.16.0"},{"fix":"Upgrade your Python environment to 3.8 or newer. Ensure `Pillow` is installed (`pip install Pillow`). If you need Python 3.7, use sphinx-gallery<0.15.0.","message":"Support for Python 3.7 was dropped. Additionally, `Pillow` was added as a required dependency.","severity":"breaking","affected_versions":">=0.15.0"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}