Registry / web-framework / sphinxcontrib-youtube

sphinxcontrib-youtube

library1.5.0pypypiunverified

sphinxcontrib-youtube is a Sphinx extension that enables embedding YouTube, Vimeo, and PeerTube videos directly into reStructuredText or MyST documentation. It is currently at version 1.5.0 and is actively maintained with several releases per year addressing compatibility with Sphinx, adding new features, and bug fixes.

web-framework serialization

pip install sphinxcontrib-youtube

github ↗package ↗

INSTALL

IMPORT

SIG · SPHINXCONTRIB-YOUT

sphinxcontrib-youtube

web-frameworkpythonv1.5.0

Install

5.2s 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 v1.5.0 · 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.2s · import 0.000s · 93MB

94MB installed

● package 94MB

Code

Verified usage

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

sphinxcontrib.youtube

✓ extensions = ['sphinxcontrib.youtube']

✗ extensions = ['youtube']

Sphinx extensions in the `sphinxcontrib` namespace must be referenced with their full dotted path in `conf.py`.

To enable `sphinxcontrib-youtube`, add `'sphinxcontrib.youtube'` to the `extensions` list in your Sphinx project's `conf.py` file. Then, use the `.. youtube::` directive in your reStructuredText or MyST files, providing the full URL to the video.

# conf.py import os import sys project = 'My Sphinx Project' copyright = '2023, Your Name' extensions = [ 'sphinxcontrib.youtube', ] # html_theme = 'alabaster' # Or any other Sphinx theme # In your .rst or .md file (e.g., index.rst): # # .. youtube:: https://www.youtube.com/watch?v=dQw4w9WgXcQ # :width: 560 # :height: 315 # :align: center # :alt: Example YouTube Video # # For Vimeo or PeerTube, use their respective full URLs. # .. youtube:: https://vimeo.com/209761509 # :width: 560 # :height: 315

Debug

Known issues

gotchaWhen adding the extension to `conf.py`, ensure you use the full dotted name `sphinxcontrib.youtube`, not just `youtube`.

fix

In `conf.py`, change `extensions = ['youtube']` to `extensions = ['sphinxcontrib.youtube']`.

affects: All versions

deprecatedPython 3.5 is no longer supported. Version 1.0.1 was released specifically to support Python 3.5 by removing f-strings, but subsequent versions have moved to maintain compatibility with actively supported Python versions (typically Python 3.6+).

fix

Upgrade your Python environment to 3.6 or newer. If stuck on Python 3.5, you might be limited to `sphinxcontrib-youtube==1.0.1` and older Sphinx versions.

affects: >=1.0.2

gotchaWhen building LaTeX output, `sphinxcontrib-youtube` downloads video thumbnails. This process requires network access and can increase build times. If your build environment is offline or has strict network policies, LaTeX builds might fail or be significantly slower.

fix

Ensure your build environment has network access during LaTeX builds. If building offline, consider disabling LaTeX output or checking `sphinxcontrib-youtube`'s configuration options for thumbnail handling (though direct options for this might be limited, it downloads them by default if targeting LaTeX).

affects: >=1.2.0

gotchaVideo URLs must be complete, including the `http://` or `https://` scheme. Relative paths or IDs without a full URL scheme may not render correctly.

fix

Always provide the full, absolute URL to the video, e.g., `https://www.youtube.com/watch?v=dQw4w9WgXcQ`.

affects: All versions

Upgrade

Version history

1.5.0latest on PyPI · released Apr 1, 2026

Audit

Dependencies

SphinxrequiredRequired for Sphinx documentation projects. `sphinxcontrib-youtube` requires `Sphinx>=4.0`.

Agent activity

9 hits · last 30 days

node

Resources

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

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