Alabaster

1.0.0 verified Tue May 12 auth: no python install: verified

Alabaster is a visually clean, responsive, and configurable theme for the Sphinx documentation system. It is currently at version 1.0.0 and is actively maintained, with releases typically tied to Sphinx compatibility and feature enhancements. It started as a third-party theme but is now an install-time dependency and the default theme for Sphinx since version 1.3.

pip install alabaster

Common errors

error ModuleNotFoundError: No module named 'sphinx' ↓

cause Sphinx is not installed in the Python environment.

fix

pip install sphinx

error ImportError: cannot import name 'ABC' from 'abc' ↓

cause Attempting to import 'ABC' from 'abc' in Python 2, where 'ABC' is not available.

fix

from abc import ABCMeta as ABC

error ImportError: cannot import name 'get_app' from partially initialized module 'prompt_toolkit.application.current' ↓

cause Circular import issue in 'prompt_toolkit' due to version incompatibility.

fix

pip install 'prompt-toolkit<3.0.0'

error Theme error: no theme named 'alabaster' found ↓

cause Sphinx cannot locate the 'alabaster' theme files, possibly due to an incorrect `html_theme_path` configuration, an incompatible Sphinx version, or `alabaster` not being explicitly installed in the environment if an older Sphinx version is used.

fix

Ensure alabaster is installed in your environment (pip install alabaster). In your conf.py, explicitly set html_theme = 'alabaster'. If you have a custom html_theme_path, ensure it correctly points to the location where alabaster is installed, for example by using import alabaster; html_theme_path = [alabaster.get_path()].

error Sphinx Alabaster theme TOC not showing in all pages ↓

cause The `html_sidebars` setting in your `conf.py` is either missing, incorrectly configured, or does not include the necessary Alabaster sidebar templates like `navigation.html` or `about.html`.

fix

Explicitly define the html_sidebars setting in your conf.py to include Alabaster's customized templates. A common configuration is:

html_sidebars = {
    '**': [
        'about.html',
        'navigation.html',
        'searchbox.html',
        'donate.html',
    ]
}

Adjust the list of .html files as needed for your documentation.

Warnings

breaking Alabaster 1.0.0 dropped support for Python 3.9 and earlier, and Sphinx 6.1 and earlier. ↓

fix Ensure your project uses Python 3.10+ and Sphinx 6.2+ before upgrading to Alabaster 1.0.0.

breaking The layout changed significantly between Alabaster 0.7.16 and 1.0.0 due to the removal of `@import url("basic.css");` from `alabaster.css`. This can cause tables, TOCs, and figures to display incorrectly, potentially extending beyond screen width. ↓

fix If you use a custom stylesheet, you might need to add `@import '../basic.css';` to your `custom.css` file to re-include the basic Sphinx styling. It is also recommended to review your theme options and custom CSS for compatibility after the upgrade.

deprecated The `canonical_url` theme option was deprecated in Alabaster 0.7.15 in favor of Sphinx's `html_baseurl` configuration. ↓

fix Use `html_baseurl` directly in your `conf.py` instead of setting `canonical_url` within `html_theme_options`.

gotcha Some older theme options (implemented prior to 0.7.8) that modify minor styles might be more appropriately handled via custom CSS stylesheet overrides. The theme maintainers now generally prefer custom stylesheets for small CSS modifications. ↓

fix For minor style adjustments not directly covered by `html_theme_options`, consider creating a custom CSS file (e.g., `_static/custom.css`) and referencing it in `conf.py` using `html_static_path = ['_static']` and `html_css_files = ['css/custom.css']`.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.00s 17.9M

3.10 alpine (musl) - - 0.00s 17.9M

3.10 slim (glibc) wheel 1.5s 0.00s 18M

3.10 slim (glibc) - - 0.00s 18M

3.11 alpine (musl) wheel - 0.00s 19.7M

3.11 alpine (musl) - - 0.00s 19.7M

3.11 slim (glibc) wheel 1.5s 0.00s 20M

3.11 slim (glibc) - - 0.00s 20M

3.12 alpine (musl) wheel - 0.00s 11.6M

3.12 alpine (musl) - - 0.00s 11.6M

3.12 slim (glibc) wheel 1.4s 0.00s 12M

3.12 slim (glibc) - - 0.00s 12M

3.13 alpine (musl) wheel - 0.00s 11.3M

3.13 alpine (musl) - - 0.00s 11.2M

3.13 slim (glibc) wheel 1.4s 0.00s 12M

3.13 slim (glibc) - - 0.00s 12M

3.9 alpine (musl) wheel - 0.00s 17.3M

3.9 alpine (musl) - - 0.00s 17.3M

3.9 slim (glibc) wheel 1.7s 0.00s 18M

3.9 slim (glibc) - - 0.00s 18M

Imports

alabaster.get_path
wrong
```
import alabaster
html_theme_path = ['_themes/alabaster_copy_dir']
html_theme = 'alabaster'
```
correct
```
import alabaster
html_theme_path = [alabaster.get_path()]
extensions = ['alabaster']
html_theme = 'alabaster'
```
`alabaster.get_path()` dynamically returns the install location, ensuring Sphinx can find the theme regardless of installation method. Manually copying theme files or directly modifying Jinja templates for customization is generally not the recommended approach.

Quickstart last tested: 2026-04-24

This quickstart guides you through configuring an existing Sphinx project to use the Alabaster theme. It demonstrates how to set the theme path using `alabaster.get_path()`, enable the `alabaster` extension, and apply common `html_theme_options` and `html_sidebars` configurations within your Sphinx `conf.py` file.

# 1. First, set up a basic Sphinx project (if you haven't already):
#    sphinx-quickstart
#    (accept defaults or configure as needed)

# 2. In your conf.py (located in your Sphinx project's source directory):
import os
import sys
import alabaster

# Project information
project = 'My Awesome Project'
copyright = '2026, Your Name'
author = 'Your Name'
release = '0.1.0'

# -- General configuration ---------------------------------------------------
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx.ext.viewcode',
    'alabaster' # Important: include 'alabaster' in extensions
]

templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

# -- Options for HTML output -------------------------------------------------
html_theme = 'alabaster'
html_theme_path = [alabaster.get_path()] # This dynamically sets the theme path

# Optional: Alabaster theme options (customize appearance)
html_theme_options = {
    'logo': 'logo.png', # Requires a logo.png in _static/ if used
    'github_user': 'your-github-user',
    'github_repo': 'your-github-repo',
    'description': 'A brief description of your project.',
    'fixed_sidebar': True,
    'show_relbars': True,
    'show_related': True,
    'sidebar_width': '250px'
    # Many other options available, see Alabaster documentation
}

# Optional: Custom sidebar templates, maps document names to template names.
# Alabaster provides about.html, navigation.html, searchbox.html, donate.html
# searchbox.html comes with Sphinx itself.
html_sidebars = {
    '**': [
        'about.html',
        'navigation.html',
        'searchbox.html',
        'donate.html'
    ]
}

# If you have custom CSS, add it here (e.g., in _static/custom.css)
# html_static_path = ['_static']
# html_css_files = [
#     'css/custom.css',
# ]

# To build your docs:
# cd <your_sphinx_project_root>
# make html