Install & Compatibility
Where this runs
tested against v1.0.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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 17.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
alabaster.get_path
✓ import alabaster
html_theme_path = [alabaster.get_path()]
extensions = ['alabaster']
html_theme = 'alabaster'
✗ import alabaster
html_theme_path = ['_themes/alabaster_copy_dir']
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.
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
Debug
Known issues
breakingAlabaster 1.0.0 dropped support for Python 3.9 and earlier, and Sphinx 6.1 and earlier.fixEnsure your project uses Python 3.10+ and Sphinx 6.2+ before upgrading to Alabaster 1.0.0.
affects: 1.0.0 and later
breakingThe 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.fixIf 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.
affects: 1.0.0 and later (when upgrading from versions prior to 1.0.0)
deprecatedThe `canonical_url` theme option was deprecated in Alabaster 0.7.15 in favor of Sphinx's `html_baseurl` configuration.fixUse `html_baseurl` directly in your `conf.py` instead of setting `canonical_url` within `html_theme_options`.
affects: 0.7.15 and later
gotchaSome 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.fixFor 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']`.
affects: 0.7.8 and later
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'sphinx'
Sphinx is not installed in the Python environment.
ImportError: cannot import name 'ABC' from 'abc'
Attempting to import 'ABC' from 'abc' in Python 2, where 'ABC' is not available.
fixfrom abc import ABCMeta as ABC
ImportError: cannot import name 'get_app' from partially initialized module 'prompt_toolkit.application.current'
Circular import issue in 'prompt_toolkit' due to version incompatibility.
fixpip install 'prompt-toolkit<3.0.0'
Theme error: no theme named 'alabaster' found
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.
fixEnsure `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()]`.
Sphinx Alabaster theme TOC not showing in all pages
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`.
fixExplicitly define the `html_sidebars` setting in your `conf.py` to include Alabaster's customized templates. A common configuration is:
```python
html_sidebars = {
'**': [
'about.html',
'navigation.html',
'searchbox.html',
'donate.html',
]
}
```
Adjust the list of `.html` files as needed for your documentation. Upgrade
Version history
1.0.0latest on PyPI · released Jul 26, 2024
Audit
Dependencies
SphinxrequiredAlabaster is a theme for Sphinx and requires it to generate documentation. Alabaster 1.0.0 requires Sphinx 6.2 or newer.