PySpelling

2.12.1 · active · verified Thu Apr 16

PySpelling is a powerful spell checker for various text formats, including Markdown, reStructuredText, HTML, and Python source code. It acts as a wrapper for external spell checkers like Aspell or Hunspell, providing a unified configuration and reporting interface. Currently at version 2.12.1, it typically releases new versions every few months, often incorporating new Python version support, minor features, and bug fixes.

Common errors

```
sh: aspell: command not found
```
cause The Aspell spell checker is not installed or not in your system's PATH.

fix Install Aspell on your operating system. For Debian/Ubuntu: `sudo apt-get install aspell aspell-en`. For macOS: `brew install aspell`.
```
sh: hunspell: command not found
```
cause The Hunspell spell checker is not installed or not in your system's PATH.

fix Install Hunspell on your operating system. For Debian/Ubuntu: `sudo apt-get install hunspell hunspell-en-us`. For macOS: `brew install hunspell`.
```
Error: No configuration file found. Please provide one with -c or place .pyspelling.yml in the current directory.
```
cause PySpelling could not find its configuration file (`.pyspelling.yml`).

fix Create a `.pyspelling.yml` file in your current working directory, or specify its path using `pyspelling -c /path/to/config.yml`.
```
Error loading config file: ... (e.g., YAMLError: while parsing a block mapping)
```
cause Your `.pyspelling.yml` file contains YAML syntax errors (e.g., incorrect indentation, missing colons).

fix Review and correct the YAML syntax in your `.pyspelling.yml` file. Tools like online YAML validators can help.
```
ModuleNotFoundError: No module named 'pyspelling'
```
cause The pyspelling Python package is not installed in your current Python environment.

fix Install the package using pip: `pip install pyspelling`.

Warnings

breaking Python 3.6, 3.7, and 3.8 are no longer supported. Ensure your environment uses Python 3.9 or newer.
Fix: Upgrade your Python environment to 3.9+ (e.g., Python 3.9, 3.10, 3.11, 3.12, 3.13, 3.14).
gotcha PySpelling requires an external spell checker like Aspell or Hunspell to be installed on your system. It does not provide its own spell checking engine.
Fix: Install Aspell (e.g., `sudo apt-get install aspell aspell-en` on Debian/Ubuntu, `brew install aspell` on macOS) or Hunspell on your operating system.
gotcha The configuration file (`.pyspelling.yml`) must be valid YAML. Incorrect indentation or syntax can lead to parsing errors.
Fix: Carefully review your `.pyspelling.yml` file for YAML syntax errors. Use a YAML linter if unsure.
gotcha Dictionary compilation can be slow for large custom dictionaries. Starting with 2.11, `--skip-dict-compile` can be used to skip recompilation if the dictionary exists and hasn't changed.
Fix: Use `pyspelling --skip-dict-compile` to speed up subsequent runs when custom dictionaries are stable. Note that changes to a custom dictionary will be ignored with this option.

Install

pip install pyspelling Install PySpelling

Imports

Pyspelling
```
from pyspelling import Pyspelling
```
While PySpelling can be used programmatically, its primary use case is via the command-line interface with a configuration file.

Quickstart

Create a `.pyspelling.yml` configuration file and then run `pyspelling` from your terminal. This example checks Markdown files using Aspell and a custom wordlist. Ensure you have Aspell or Hunspell installed on your system.

echo "sources:\n  - './*.md'\naspell:\n  lang: en\n  d: en_US\ndictionary:\n  wordlists:\n    - .pyspelling_wordlist.txt\n  encoding: utf-8\n" > .pyspelling.yml

echo "# My Document\n\nThis is a test with a mispelled word: misstake." > test.md

# Run spell check
pyspelling

# Expected output (simplified, actual output depends on Aspell/Hunspell installation):
# test.md:2: misstake

view raw JSON →