Registry / web-framework / sphinxcontrib-video

sphinxcontrib-video

library0.4.2pypypiunverified

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.

web-framework

pip install sphinxcontrib-video

github ↗package ↗

INSTALL

IMPORT

SIG · SPHINXCONTRIB-VIDE

sphinxcontrib-video

web-frameworkpythonv0.4.2

Install

5.3s avg

Import

—

Disk

94MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.4.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.000s · 92.2MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 5.3s · import 0.000s · 93MB

94MB installed

● package 94MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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:

Debug

Known issues

gotchaThe 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`.

affects: All versions

gotchaWhen 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.

affects: All versions

gotchaCustom 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.

affects: All versions

gotchaThe 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.

affects: 0.4.0 and later

Upgrade

Version history

0.4.2latest on PyPI · released Jan 14, 2026

Audit

Dependencies

SphinxrequiredThis is a Sphinx extension and requires Sphinx to function.

PythonrequiredRequires Python 3.9 or newer.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/sphinx-contrib/video ↗

packagehttps://pypi.org/project/sphinxcontrib-video/ ↗