Registry / testing / sphinxcontrib-spelling

sphinxcontrib-spelling

library8.0.2pypypi✓ verified 24d ago

sphinxcontrib.spelling is a spelling checker extension for Sphinx-based documentation. It leverages PyEnchant to analyze reStructuredText and Markdown files, generating reports of misspelled words. The current version is 8.0.2, and the project maintains an active development with regular releases addressing bugs and adding features. [1, 3, 11, 12, 14]

testing devops

pip install sphinxcontrib-spelling

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SPHINXCONTRIB-SPEL

sphinxcontrib-spelling

testingpythonv8.0.2

Install

5.5s avg

Import

—

Disk

95MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v8.0.2 · 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.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 5.5s · import 0.000s · 93MB

95MB installed

● package 95MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

'sphinxcontrib.spelling'

✓ # in conf.py extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinxcontrib.spelling' ]

The extension is enabled by adding its module name to the 'extensions' list in Sphinx's conf.py. There are no direct Python imports of classes from sphinxcontrib.spelling for typical usage.

To quickly set up `sphinxcontrib-spelling`, first ensure PyEnchant and the extension are installed. Then, configure your Sphinx `conf.py` to include the extension and define basic spelling options like language and custom word lists. Finally, run the `sphinx-build` command with the `-b spelling` option to execute the spell checker, which will output misspelled words to the console and a log file. [4, 8, 9, 15]

# 1. Install PyEnchant and sphinxcontrib-spelling (see install instructions). # 2. In your Sphinx project's conf.py file: extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinxcontrib.spelling' ] spelling_lang = 'en_US' spelling_word_list_filename = ['spelling_wordlist.txt'] spelling_show_suggestions = True # 3. Create a 'spelling_wordlist.txt' file in your project root with custom words (one per line). # Example: 'MyBrandName', 'JargonTerm' # 4. Build your documentation to check spelling. Run this command in your project root: # sphinx-build -b spelling docs/source docs/build/spelling # (Assuming 'docs/source' is your source directory and 'docs/build' is your build directory.)

Debug

Known issues

gotchaThe spell checking functionality relies on PyEnchant, which requires a system-level Enchant library to be installed. If PyEnchant is not installed or correctly configured with Enchant, spell checking will not work, though the extension itself might initialize without error. [1, 13, 20]

fix

Ensure `enchant` (system library) and `pyenchant` (Python package) are correctly installed and discoverable by your Python environment.

affects: All versions

gotchaThe spell checker runs as a dedicated Sphinx builder. It does not automatically run when you build other formats like HTML or LaTeX. You must explicitly run `sphinx-build -b spelling` as a separate step. [5, 8]

fix

Execute `sphinx-build -b spelling <source_dir> <build_dir>` as a distinct command to perform spell checking.

affects: All versions

breakingVersion `7.7.1` was yanked from PyPI because it introduced a breaking change without a corresponding semantic version update. Users should avoid this specific version. [12]

fix

Upgrade to a later stable version (e.g., 8.0.2) or downgrade to a prior stable version if necessary.

affects: 7.7.1

gotchaSpell check results can be inconsistent across different operating systems or environments (e.g., Windows vs. Linux CI/CD). This is often due to variations in PyEnchant's underlying Enchant dictionary installations or configurations. [20]

fix

Standardize the Enchant and PyEnchant installations across all development and build environments, potentially specifying exact versions or using Docker for consistency. Configure `spelling_lang` explicitly.

affects: All versions

breakingOlder versions (prior to 8.0.0) might encounter a `TypeError` when processing nodes without source information, especially with Sphinx 8.2 or newer. [19]

fix

Upgrade to `sphinxcontrib-spelling` version 8.0.0 or newer to ensure compatibility with Sphinx 8.2+.

affects: <8.0.0

Upgrade

Version history

8.0.2latest on PyPI · released Nov 28, 2025

Audit

Dependencies

PyEnchantoptionalProvides the core spell-checking dictionaries and functionality. While optional for installation, spell checking will not work without it.

SphinxrequiredThis is a Sphinx extension and requires Sphinx to operate.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/sphinx-contrib/spelling ↗

packagehttps://pypi.org/project/sphinxcontrib-spelling/ ↗

homepagehttps://sphinxcontrib-spelling.readthedocs.io/en/latest/ ↗