Shibuya Sphinx Theme

2026.1.9 verified Mon Apr 27 auth: no python

A clean, responsive, and customizable Sphinx documentation theme with light/dark mode. Current version 2026.1.9, requires Python >=3.10. Active development with frequent releases.

pip install shibuya

Common errors

error html_theme = 'shibuya' Theme 'shibuya' not found ↓

cause Shibuya is not installed or the package name is misspelled.

fix

Run pip install shibuya and ensure you are using the correct theme name (all lowercase).

error sphinx.errors.ThemeError: unknown theme 'shibuya' ↓

cause Sphinx cannot find the theme; it may not be installed in the same environment.

fix

Install shibuya via pip in your Sphinx environment: pip install shibuya.

error TypeError: 'NoneType' object is not subscriptable in shibuya theme ↓

cause Missing required configuration, e.g., 'logo' or 'accent_color' options set to None.

fix

Ensure all theme options are defined with proper string values, or remove the option to use defaults.

Warnings

gotcha The theme is configured via `html_theme = 'shibuya'` in conf.py, not by importing a package. Users new to Sphinx often try `import shibuya` which does nothing. ↓

fix Set `html_theme = 'shibuya'` in your Sphinx conf.py file.

breaking From version 2025.12.13, a 'Copy Page' button and 'Open in AI' dropdown are added by default. If you have custom CSS or JavaScript, these may overlap. ↓

fix To disable, add `'copy_button': False` and/or `'open_in_ai': False` to html_theme_options.

deprecated The 'source_url' option for edit button is deprecated. Use 'edit_page_url' or 'raw_source_url' instead. ↓

fix Replace `'source_url': ...` with `'edit_page_url': ...` in theme options.

gotcha When using `raw_source_url`, the path must be absolute URL. Relative paths cause errors in the copy page button. ↓

fix Ensure `raw_source_url` starts with `https://` or is a full URL.

Imports

html_theme
```
html_theme = 'shibuya'  # in conf.py
```
Set html_theme in Sphinx conf.py, not an import statement. There is no Python module to import.

Quickstart

Configure Shibuya as your Sphinx documentation theme.

# In your Sphinx conf.py
import os

html_theme = 'shibuya'
html_theme_options = {
    'accent_color': 'blue',
    'light_logo': 'logo-light.png',
    'dark_logo': 'logo-dark.png',
}