sphinx-tabs

library3.5.0pypypi✓ verified 23d ago

Sphinx Tabs is a Sphinx extension that provides directives for creating tabbed content in Sphinx documentation when building HTML. It is actively maintained, with version 3.5.0 currently available, and releases frequently address compatibility with new Sphinx and Docutils versions.

web-framework

pip install sphinx-tabs

github ↗package ↗

INSTALL

IMPORT

SIG · SPHINX-TABS

sphinx-tabs

web-frameworkpythonv3.5.0

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 v3.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.95 runs

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

glibc

py 3.10–3.95 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.

sphinx_tabs.tabs

✓ extensions = ['sphinx_tabs.tabs']

Add 'sphinx_tabs.tabs' to the 'extensions' list in your conf.py to enable the extension.

This quickstart guides you through setting up a basic Sphinx project, enabling the `sphinx-tabs` extension, and creating an example reStructuredText file with a tabbed interface. After building, you can view the tabbed content in the generated HTML documentation.

mkdir myproject cd myproject mkdir docs cd docs sphinx-quickstart # Follow prompts, say 'y' to Separate source and build dirs # In docs/conf.py: # extensions = [ # 'sphinx.ext.autodoc', # 'sphinx.ext.napoleon', # 'sphinx_tabs.tabs', # ] # html_theme = 'alabaster' # Or any other Sphinx theme # In docs/index.rst: # .. _index: # # Welcome to My Sphinx Tabs Project's documentation! # ================================================== # # .. tabs:: # # .. tab:: Python # # .. code-block:: python # # def hello_world(): # print("Hello, Python!") # # .. tab:: Shell # # .. code-block:: bash # # echo "Hello, Shell!" # # .. tab:: Markup # # Hello from **reStructuredText**! # # This project demonstrates `sphinx-tabs` functionality. # # Indices and tables # ================== # # * :ref:`genindex` # * :ref:`modindex` # * :ref:`search` # Then build: # make html # Open _build/html/index.html

Debug

Known issues

breakingsphinx-tabs v3.5.0 (and newer versions) officially dropped support for Sphinx versions older than 7. Ensure your Sphinx installation is version 7 or higher when upgrading sphinx-tabs to 3.5.0+.

fix

Upgrade your Sphinx version to 7 or newer (`pip install 'sphinx>=7'`) or pin sphinx-tabs to an older compatible version (`pip install 'sphinx-tabs<3.5.0'`).

affects: >=3.5.0

gotchaThe `.. include::` directive does not function correctly when placed inside a `.. code-tab::` directive. For including general reStructuredText content within tabs, use `.. tab::` or `.. group-tab::` instead.

fix

Refactor your reStructuredText to use `.. tab::` or `.. group-tab::` for content that needs to include other files, or manually embed the content directly.

affects: All

gotchaWhen using 'grouped tabs' by providing a group name to the `.. tabs::` directive (e.g., `.. tabs:: my-group`), ensure that the tab labels you intend to synchronize are consistent across all tab sets within that group on the same page. Inconsistent labels may lead to unexpected synchronization behavior.

fix

Standardize tab labels across all `.. tabs::` blocks that share the same group name to ensure proper synchronization.

affects: All

gotchaIf you are building your documentation on Read The Docs, you must explicitly add `sphinx-tabs` to your `requirements.txt` file in your project's root or docs folder, in addition to installing it in your local environment, for the extension to be recognized during the build process.

fix

Add `sphinx-tabs` to your `requirements.txt` file (e.g., `sphinx-tabs==3.5.0`) to ensure it's installed on Read The Docs.

affects: All

gotchaSome users have reported compatibility issues with `sphinx-tabs` and certain Sphinx themes (e.g., `pydata-sphinx-theme`), where the presence of `sphinx-tabs` can interfere with theme-specific features like version switchers, even if tabs are not actively used on the page.

fix

If experiencing conflicts, check the issue trackers of both `sphinx-tabs` and your chosen Sphinx theme for known incompatibilities and potential workarounds or updates. You might need to adjust CSS or JavaScript, or consider alternative tab extensions if no fix is available.

affects: All

Upgrade

Version history

3.5.0latest on PyPI · released Mar 3, 2026

Audit

Dependencies

SphinxrequiredCore documentation generator, version >=7 is required for sphinx-tabs 3.5.0.

pythonrequiredRequires Python 3.10 or newer.

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/executablebooks/sphinx-tabs ↗

packagehttps://pypi.org/project/sphinx-tabs/ ↗