Sphinx Inline Tabs

2025.12.21.14 · active · verified Thu Apr 16

Sphinx Inline Tabs is a Sphinx extension that allows you to add inline tabbed content to your documentation. This is useful for showing different command-line flags, code examples, or other content based on user preferences. The current version is `2025.12.21.14` and it follows a non-strict release cadence, often aligned with Sphinx releases or bug fixes.

Common errors

```
(ERROR/3) Unknown directive type "tabs".
```
cause The `sphinx-inline-tabs` extension has not been enabled in your Sphinx project's configuration.

fix Add `'sphinx_inline_tabs'` to the `extensions` list in your `conf.py` file. For example: `extensions = ['sphinx.ext.autodoc', 'sphinx_inline_tabs']`.
```
(ERROR/3) Malformed tabs directive: "group-tab" must be preceded by "tabs" or similar indentation errors for tab directives.
```
cause Incorrect reStructuredText (RST) indentation or structure. `group-tab` (or `tab`) must be a child directive of `tabs` and correctly indented.

fix Review your `.rst` file. Ensure `.. group-tab::` is indented by 3 spaces relative to `.. tabs::`, and any content within `group-tab` is further indented by at least 3 spaces relative to `.. group-tab::`.

Warnings

gotcha Forgetting to add 'sphinx_inline_tabs' to the 'extensions' list in your Sphinx 'conf.py' file. This is the most common reason for the tabs not rendering or directives being unrecognized.
Fix: Ensure `extensions = ['sphinx_inline_tabs']` (or append to existing list) is present in your `conf.py`.
gotcha Incorrect reStructuredText (RST) indentation for `.. tabs::` and `.. group-tab::` directives. RST is whitespace-sensitive, and improper indentation will lead to rendering errors or unexpected output.
Fix: Carefully follow the examples in the documentation regarding indentation. `.. group-tab::` must be indented relative to `.. tabs::`, and its content must be indented further.
gotcha Potential visual inconsistencies with custom or older Sphinx themes. While `sphinx-inline-tabs` tries to be compatible, some themes might override default CSS/JS in a way that conflicts with the tab styling.
Fix: If tabs look broken, try switching to a standard Sphinx theme (e.g., `furo`, `alabaster`). If the issue persists, inspect browser developer tools for CSS conflicts or open an issue on the library's GitHub page.

Install

pip install sphinx-inline-tabs Install latest version

Imports

sphinx_inline_tabs
wrong:
```
from sphinx_inline_tabs import ...
```
correct:
```
extensions = ['sphinx_inline_tabs']
```
This library is a Sphinx extension, not typically imported as a Python module in user code. It's enabled by adding its name to the `extensions` list in your Sphinx `conf.py` file.

Quickstart

To quickly use `sphinx-inline-tabs`, first create a basic Sphinx project (`sphinx-quickstart`). Then, add `sphinx_inline_tabs` to the `extensions` list in your `conf.py` file. Finally, define tabbed content using the `.. tabs::` directive and `.. group-tab::` (or `.. tab::`) sub-directives in your reStructuredText files, ensuring correct indentation. The provided code snippet shows the `conf.py` modification and an example RST structure.

# conf.py
extensions = [
    'sphinx_inline_tabs',
]

# index.rst (or any other .rst file where you want tabs)
# .. tabs::
#
#    .. group-tab:: Python
#
#       .. code-block:: python
#
#          print("Hello from Python")
#
#    .. group-tab:: Go
#
#       .. code-block:: go
#
#          package main
#          import "fmt"
#          func main() {
#              fmt.Println("Hello from Go")
#          }

view raw JSON →