Registry / devops / mkdocs-spellcheck

mkdocs-spellcheck

library1.2.1pypypi✓ verified 84d ago

A spell checker plugin for MkDocs that checks spelling in Markdown content. It supports multiple backends (e.g., aspell, hunspell) and allows custom dictionaries. Current version 1.2.1 (2026-02-11), requires Python >=3.10, actively maintained on GitHub by pawamoy.

devops testing

pip install mkdocs-spellcheck

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · MKDOCS-SPELLCHECK

mkdocs-spellcheck

devopspythonv1.2.1

Install

3.0s avg

Import

568ms

Disk

32MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.2.1 · 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.915 runs

installs and imports cleanly · install 0.0s · import 0.576s · 33.1MB

glibc

py 3.10–3.915 runs

installs and imports cleanly · install 3.0s · import 0.560s · 34MB

32MB installed

● package 32MB

Code

Verified usage

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

SpellCheckPlugin

✓ from mkdocs_spellcheck import SpellCheckPlugin

✗ from mkdocs_spellcheck.plugin import SpellCheckPlugin

Submodule imports deprecated since 1.1.1

config

✓ from mkdocs_spellcheck import config

✗ from mkdocs_spellcheck.config import config

Top-level imports are preferred; submodules deprecated

Enable the spellcheck plugin in your MkDocs configuration. Add known words to avoid false positives. The search plugin must be listed before spellcheck for compatibility.

# mkdocs.yml plugins: - search - spellcheck: known_words: - mkdocs - spellcheck backends: - hunspell # Optional: ignore code blocks ignore_code: true

Debug

Known issues

breakingImporting from submodules (e.g., `from mkdocs_spellcheck.plugin import SpellCheckPlugin`) is deprecated since v1.1.1 and will be removed in a future release. Always import from the top-level `mkdocs_spellcheck`.

fix

Use `from mkdocs_spellcheck import SpellCheckPlugin` instead.

affects: >=1.1.1

gotchaPlugin initialization may fail if `search` plugin is not listed before `spellcheck` in the plugins list. The order matters in MkDocs.

fix

Place `search` before `spellcheck` in mkdocs.yml plugins list.

affects: all

gotchaBackends like hunspell or aspell must be installed on the system separately; the Python package only provides bindings. If no backend is available, the plugin will skip spellchecking silently unless misconfigured.

fix

Install system package (e.g., `sudo apt install hunspell`) and ensure Python bindings are installed (e.g., `pip install hunspell`).

affects: all

deprecatedThe `aspell` backend is no longer actively supported and may be removed in a future version. It is recommended to use `hunspell` instead.

fix

Switch to hunspell backend.

affects: >=1.2.0?

Errors

Common errors & fixes

'NoneType' object has no attribute 'items'

The spellcheck plugin is misconfigured or the known_words key is missing or malformed.

fix

Ensure `known_words` is a list of strings under the spellcheck plugin block in mkdocs.yml.

module 'mkdocs_spellcheck' has no attribute 'plugin'

Importing from submodules after v1.1.1 when they are deprecated and possibly removed.

fix

Use top-level imports: `from mkdocs_spellcheck import SpellCheckPlugin`.

Spellcheck failed: unable to load backend 'hunspell'

The hunspell system library is not installed or the Python bindings are missing.

fix

Install system hunspell (e.g., `sudo apt install hunspell`) and Python bindings (`pip install hunspell`).

Upgrade

Version history

1.2.1latest on PyPI · released Feb 11, 2026

Audit

Dependencies

pyyamlrequiredUsed for config parsing in mkdocs-plugin

mkdocsrequiredPlugin host

hunspelloptionalOptional backend for spell checking

aspelloptionalOptional backend for spell checking

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/pawamoy/mkdocs-spellcheck ↗

packagehttps://pypi.org/project/mkdocs-spellcheck/ ↗

homepagehttps://pawamoy.github.io/mkdocs-spellcheck ↗

docshttps://pawamoy.github.io/mkdocs-spellcheck ↗

changeloghttps://pawamoy.github.io/mkdocs-spellcheck/changelog ↗