{"id":7743,"library":"sphinxcontrib-youtube","title":"Sphinx YouTube Extension","description":"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.","status":"active","version":"1.5.0","language":"en","source_language":"en","source_url":"https://github.com/sphinx-contrib/youtube","tags":["sphinx","documentation","extension","youtube","vimeo","peertube","rst","myst"],"install":[{"cmd":"pip install sphinxcontrib-youtube","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for Sphinx documentation projects. `sphinxcontrib-youtube` requires `Sphinx>=4.0`.","package":"Sphinx","optional":false}],"imports":[{"note":"Sphinx extensions in the `sphinxcontrib` namespace must be referenced with their full dotted path in `conf.py`.","wrong":"extensions = ['youtube']","symbol":"sphinxcontrib.youtube","correct":"extensions = ['sphinxcontrib.youtube']"}],"quickstart":{"code":"# conf.py\n\nimport os\nimport sys\n\nproject = 'My Sphinx Project'\ncopyright = '2023, Your Name'\n\nextensions = [\n    'sphinxcontrib.youtube',\n]\n\n# html_theme = 'alabaster' # Or any other Sphinx theme\n\n# In your .rst or .md file (e.g., index.rst):\n#\n# .. youtube:: https://www.youtube.com/watch?v=dQw4w9WgXcQ\n#    :width: 560\n#    :height: 315\n#    :align: center\n#    :alt: Example YouTube Video\n#\n# For Vimeo or PeerTube, use their respective full URLs.\n# .. youtube:: https://vimeo.com/209761509\n#    :width: 560\n#    :height: 315\n","lang":"python","description":"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."},"warnings":[{"fix":"In `conf.py`, change `extensions = ['youtube']` to `extensions = ['sphinxcontrib.youtube']`.","message":"When adding the extension to `conf.py`, ensure you use the full dotted name `sphinxcontrib.youtube`, not just `youtube`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Python 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+).","severity":"deprecated","affected_versions":">=1.0.2"},{"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).","message":"When 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.","severity":"gotcha","affected_versions":">=1.2.0"},{"fix":"Always provide the full, absolute URL to the video, e.g., `https://www.youtube.com/watch?v=dQw4w9WgXcQ`.","message":"Video URLs must be complete, including the `http://` or `https://` scheme. Relative paths or IDs without a full URL scheme may not render correctly.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Change `extensions = ['youtube']` to `extensions = ['sphinxcontrib.youtube']` in your `conf.py` file.","cause":"The extension name was incorrectly specified in `conf.py`.","error":"Sphinx error: unknown extension: 'youtube'"},{"fix":"Verify the package name: `pip install sphinxcontrib-youtube`. Ensure your internet connection is active.","cause":"Typo in the package name during `pip install` or PyPI is unreachable.","error":"ERROR: Could not find a version that satisfies the requirement sphinxcontrib-youtube (from versions: none)\nERROR: No matching distribution found for sphinxcontrib-youtube"},{"fix":"Upgrade your Python environment to 3.6 or newer. Refer to the `deprecated` warning regarding Python 3.5 support.","cause":"This error or similar Python syntax errors can occur if you are running a `sphinxcontrib-youtube` version that uses newer Python features (e.g., f-strings) on an older Python environment (like Python 3.5).","error":"TypeError: unsupported operand type(s) for +: 'NoneType' and 'str'"},{"fix":"1. Check the video URL for correctness (must be full `https://` URL). 2. Inspect your browser's developer console for JavaScript errors. 3. Ensure your build environment has network access if generating LaTeX/PDF output.","cause":"This can be due to an incorrect or malformed video URL, network issues preventing thumbnail download for LaTeX, or JavaScript blockers in the browser for HTML.","error":"Video does not appear in the generated HTML/PDF output."}]}