Sphinxcontrib Video

0.4.2 · active · verified Wed Apr 15

sphinxcontrib-video is a Sphinx extension that allows developers and technical writers to embed HTML5 videos (MP4, WebM, Ogg) directly into their Sphinx-generated documentation. It acts as a wrapper around the HTML5 `<video>` tag, exposing most of its parameters as directive options. The library is actively maintained, with the current stable version being 0.4.2, released on January 14, 2026, and typically follows a periodic release cadence.

Warnings

gotcha The extension will not load if 'sphinxcontrib.video' is not correctly added to the 'extensions' list in `conf.py`. Common errors include typos or forgetting to add it after installation, leading to 'Could not import extension' errors.
Fix: Ensure `extensions = ['sphinxcontrib.video']` is present and correct in your `conf.py`.
gotcha When embedding local videos, ensure their paths are correctly configured and accessible to Sphinx. Often, local video files should be placed in the `_static` directory and `html_static_path = ['_static']` should be set in `conf.py` for Sphinx to copy them to the build output. Incorrect paths will result in broken video embeds in the generated HTML.
Fix: Place local videos in your project's `_static` folder and confirm `html_static_path` is configured. Use relative paths like `_static/my_video.mp4` in the `video` directive.
gotcha Custom styling for video captions or alignment (e.g., centering) is not automatically handled by all Sphinx themes. While the `video` directive supports a `:caption:` option, its appearance and positioning often require custom CSS rules to achieve desired aesthetics, particularly for complex layouts or precise centering.
Fix: If default styling is insufficient, add custom CSS to your Sphinx project (e.g., in `_static/custom.css` linked via `html_css_files` in `conf.py`) to target the video and caption HTML elements.
gotcha The default alignment behavior for videos without an explicit `:align:` option was changed in some versions. Previously, it might have defaulted to `left`. To ensure theme-defined alignment or no specific alignment, it's recommended to explicitly set `:align: default` if you observe unexpected alignment.
Fix: If video alignment is not as expected, try adding `:align: default` to your `video` directive.

Install

pip install sphinxcontrib-video Install latest stable version

Imports

sphinxcontrib.video
```
extensions = ['sphinxcontrib.video']
```
This entry should be added to the `extensions` list in your Sphinx project's `conf.py` file to enable the extension. There is no direct Python import for runtime use.

Quickstart

To quickly use `sphinxcontrib-video`, first ensure it's installed. Then, add `'sphinxcontrib.video'` to the `extensions` list in your `conf.py`. If you plan to host local videos, configure `html_static_path` to point to your `_static` directory. Finally, use the `.. video::` reStructuredText directive in your documentation files, providing the video path and any desired HTML5 video attributes as options.

# In conf.py
import os

project = 'My Video Project'
copyright = '2026, Your Name'
extensions = [
    'sphinxcontrib.video',
]
html_static_path = ['_static'] # Required if using local videos in a '_static' folder

# In an .rst file (e.g., index.rst)
..
  _static/my_intro_video.mp4 is expected to exist
  in your Sphinx project's _static directory.

My Documentation with Video
===========================

This is an example of embedding a local HTML5 video:

.. video:: _static/my_intro_video.mp4
   :width: 60%
   :autoplay:
   :loop:
   :controls:
   :alt: An introductory video showing key features.
   :caption: A short demonstration of the project setup.

Here's an example of embedding an external video:

.. video:: https://example.com/path/to/external_video.mp4
   :poster: https://example.com/path/to/poster_image.jpg
   :width: 500
   :height: 300
   :nocontrols:

view raw JSON →