Codespell

2.4.2 · active · verified Thu Apr 09

Codespell is a Python command-line tool designed to find and fix common misspellings in text files, primarily within source code. It operates using a curated dictionary of common typos and their corrections, aiming to reduce false positives that typical spell checkers might produce with technical terms or variable names. The library is actively maintained and frequently integrated into CI/CD pipelines and pre-commit hooks for automated code quality checks.

Warnings

gotcha Using the `--write-changes` (`-w`) flag without interactive mode (`-i`) can lead to unintended automatic corrections of valid but non-standard spellings or technical jargon. It's highly recommended to use `--interactive` (`-i 2` or `-i 3`) to review suggested changes before applying them.
Fix: Always run `codespell` with `-i` (e.g., `codespell -i 3 .`) when planning to apply fixes, or review the dry run output thoroughly before using `-w`.
gotcha After installing `codespell` with `pip`, the executable might not be directly available in your system's `$PATH`. This often happens if pip installs packages to a user-specific binary directory like `~/.local/bin`.
Fix: Ensure that `~/.local/bin` is included in your system's `$PATH` environment variable. You might need to add `export PATH="$HOME/.local/bin:$PATH"` to your shell's configuration file (e.g., `.bashrc`, `.zshrc`).
breaking When `pyproject.toml` is used for configuration, Python versions prior to 3.11 require the `tomli` library to be installed. Without `tomli`, `codespell` will fail to read its configuration.
Fix: If you are using Python < 3.11 and configure `codespell` via `pyproject.toml`, ensure `pip install tomli` is executed. Python 3.11 and later include `tomli` in the standard library.
gotcha When defining custom dictionary entries with multiple suggested fixes (e.g., `fiel->feel, field, file, phial,`), a trailing comma is crucial. If omitted, the last suggestion in the list will be discarded.
Fix: Always include a trailing comma after the last suggestion when defining dictionary entries with multiple corrections. Refer to the dictionary format documentation for details.

Install

pip install codespell Install stable version

Quickstart

To get started, run `codespell` from your terminal in the directory you wish to check. By default, it performs a dry run, listing potential misspellings. Use the `-i` flag for interactive mode to review and confirm changes, or `-w` to automatically apply corrections (use with caution).

# Check for misspellings in the current directory (dry run)
codespell .

# Check specific files or directories (dry run)
codespell my_project/README.md my_project/src/

# Interactively fix misspellings in a directory (recommended for review)
codespell -i 3 my_project/

# Automatically write corrections to files (use with caution or after review)
codespell -w my_project/

view raw JSON →