---
id: sphinxcontrib-youtube
version: "1.5.0"
license: unclear
license_treatment: permissive
maintenance: active
---

# sphinxcontrib-youtube — Sphinx "youtube" extension.

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

## What it is and what it does

sphinxcontrib-youtube is a Sphinx extension that lets you embed videos from YouTube, Vimeo, and Peertube directly into reStructuredText documentation using simple directives. Instead of linking to videos externally, you can include them inline in your docs, and they render as embedded players in the final HTML output. It depends on Sphinx and requests, both widely used and stable.

You use it by adding the extension to your Sphinx conf.py, then writing directives like `.. youtube:: VIDEO_ID` in your .rst files. For Peertube, you can specify a custom instance URL. The package has been actively maintained and carries no known security vulnerabilities, making it a straightforward choice for documentation projects that want to include video content.

Use it for:

- Embed YouTube videos in Sphinx documentation to supplement written tutorials or guides.
- Include Vimeo videos in technical documentation for organizations that host content on Vimeo.
- Add Peertube videos to documentation for projects using decentralized video hosting.
- Create rich media documentation sites that combine text, code examples, and embedded video content.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Adds Sphinx directives to embed YouTube, Vimeo, and Peertube videos directly into reStructuredText documentation.

Yes. This is a lightweight, actively maintained Sphinx extension with low install friction, no security issues, and a permissive license. Install it if you need to embed videos in Sphinx documentation; skip it if your docs are text-only or you prefer external video links.

## Install

pip install sphinxcontrib-youtube
uv add sphinxcontrib-youtube
poetry add sphinxcontrib-youtube

## Installing sphinxcontrib-youtube

Before you install: Low friction install with only Sphinx and requests as runtime dependencies. Active maintenance with a recent release and a stable codebase.

License in practice: Permissive license means you can use this in commercial and private projects without restriction.

Quickstart:

pip install sphinxcontrib-youtube

In conf.py:
extensions = ['sphinxcontrib.youtube']

In your .rst file:
.. youtube:: dQw4w9WgXcQ

Verify before relying:

- Whether the package supports modern Sphinx versions and any recent breaking changes in Sphinx's extension API.
- Performance characteristics when embedding many videos in a single documentation build.

## Package facts

- License: not declared (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: active
- Downloads: 297.1K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

sphinx video embedding, youtube in sphinx docs, embed vimeo peertube sphinx, sphinx video directive, rst video inclusion, sphinx multimedia extension, sphinx-extension, documentation-tools

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