cspell
CSpell is a comprehensive spell checker for code that helps catch spelling errors in source code, documentation, and comments designed specifically for developers and technical writers.
Key Features:
- Code-Aware Checking: Understands programming languages and technical terminology, avoiding false positives on variable names, APIs, and technical terms
- Multi-Language Support: Supports 30+ programming languages with specialized dictionaries for each language and framework
- Custom Dictionaries: Extensive collection of domain-specific dictionaries (medical, scientific, legal, etc.) plus ability to create custom word lists
- Flexible Configuration: Highly configurable via JSON files with support for workspace-specific settings and ignore patterns
- Performance Optimized: Fast scanning designed for large codebases with minimal performance impact
- Developer-Friendly: Handles camelCase, PascalCase, snake_case, and other programming conventions intelligently
MegaLinter generates content of a .cspell.json config file at the end of its TextReporter artifact.
Copy it at the root of your repository, read it, remove real spelling errors (after have corrected them in the source), and you're good to go!
If you do not want cspell to analyze the files names, define SPELL_CSPELL_ANALYZE_FILE_NAMES to false
cspell documentation
- Version in MegaLinter: 10.4.0
- Visit Official Web Site
- See How to configure cspell rules
- See How to disable cspell rules in files
Configuration in MegaLinter
- Enable cspell by adding
SPELL_CSPELLin ENABLE_LINTERS variable - Disable cspell by adding
SPELL_CSPELLin DISABLE_LINTERS variable
| Variable | Description | Default value |
|---|---|---|
| SPELL_CSPELL_ANALYZE_FILE_NAMES | If set to true, MegaLinter will also send file names to cspell for analysis. Disable by defining SPELL_CSPELL_ANALYZE_FILE_NAMES to false |
true |
| SPELL_CSPELL_ARGUMENTS | User custom arguments to add in linter CLI call Ex: -s --foo "bar" |
|
| SPELL_CSPELL_COMMAND_REMOVE_ARGUMENTS | User custom arguments to remove from command line before calling the linter Ex: -s --foo "bar" |
|
| SPELL_CSPELL_FILTER_REGEX_INCLUDE | Custom regex including filter Ex: (src\|lib)⚠️ Not available with SPELL_CSPELL_CLI_LINT_MODE = project |
Exclude no file |
| SPELL_CSPELL_FILTER_REGEX_EXCLUDE | Custom regex excluding filter Ex: (test\|examples)⚠️ Not available with SPELL_CSPELL_CLI_LINT_MODE = project |
Exclude no file |
| SPELL_CSPELL_CLI_LINT_MODE | Override default CLI lint mode - file: Calls the linter for each file- list_of_files: Call the linter with the list of files as argument- project: Call the linter from the root of the project |
list_of_files |
| SPELL_CSPELL_FORWARD_EXCLUDED_DIRECTORIES | In project CLI lint mode, forward excluded directories (EXCLUDED_DIRECTORIES + ADDITIONAL_EXCLUDED_DIRECTORIES, and .gitignored directories when IGNORE_GITIGNORED_FILES is true) to the linter through its native exclusion arguments or generated ignore/config files | true |
| SPELL_CSPELL_FILE_EXTENSIONS | Allowed file extensions. "*" matches any extension, "" matches empty extension. Empty list excludes all filesEx: [".py", ""] |
Exclude every file |
| SPELL_CSPELL_FILE_NAMES_REGEX | File name regex filters. Regular expression list for filtering files by their base names using regex full match. Empty list includes all files Ex: ["Dockerfile(-.+)?", "Jenkinsfile"] |
Include every file |
| SPELL_CSPELL_PRE_COMMANDS | List of bash commands to run before the linter | None |
| SPELL_CSPELL_POST_COMMANDS | List of bash commands to run after the linter | None |
| SPELL_CSPELL_UNSECURED_ENV_VARIABLES | List of env variables explicitly not filtered before calling SPELL_CSPELL and its pre/post commands | None |
| SPELL_CSPELL_CONFIG_FILE | cspell configuration file nameUse LINTER_DEFAULT to let the linter find it |
.cspell.json |
| SPELL_CSPELL_RULES_PATH | Path where to find linter configuration file | Workspace folder, then MegaLinter default rules |
| SPELL_CSPELL_DISABLE_ERRORS | Run linter but consider errors as warnings | false |
| SPELL_CSPELL_DISABLE_ERRORS_IF_LESS_THAN | Maximum number of errors allowed | 0 |
| SPELL_CSPELL_TIMEOUT_SECONDS | Maximum duration in seconds of the linter run, after which the linter process and its child processes are killed and reported as an error (exit code 124). Overrides LINTER_TIMEOUT_SECONDS. 0 disables the timeout | 300 |
| SPELL_CSPELL_CLI_EXECUTABLE | Override CLI executable | ['cspell'] |
IDE Integration
Use cspell in your favorite IDE to catch errors before MegaLinter !
| IDE | Extension Name | Install | |
|---|---|---|---|
| Visual Studio Code | Code Spell Checker | ![]() |
MegaLinter Flavors
This linter is available in the following flavors
| Flavor | Description | Embedded linters | Info | |
|---|---|---|---|---|
![]() |
all | Default MegaLinter Flavor | 133 | |
| c_cpp | Optimized for pure C/C++ projects | 59 | ||
| cupcake | MegaLinter for the most commonly used languages | 99 | ||
| documentation | MegaLinter for documentation projects | 52 | ||
| dotnet | Optimized for C, C++, C# or VB based projects | 66 | ||
| dotnetweb | Optimized for C, C++, C# or VB based projects with JS/TS | 81 | ||
| go | Optimized for GO based projects | 54 | ||
| java | Optimized for JAVA based projects | 57 | ||
| javascript | Optimized for JAVASCRIPT or TYPESCRIPT based projects | 68 | ||
| php | Optimized for PHP based projects | 57 | ||
| python | Optimized for PYTHON based projects | 69 | ||
| ruby | Optimized for RUBY based projects | 53 | ||
| rust | Optimized for RUST based projects | 53 | ||
| salesforce | Optimized for Salesforce based projects | 58 | ||
| swift | Optimized for SWIFT based projects | 53 | ||
| terraform | Optimized for TERRAFORM based projects | 57 |
Behind the scenes
How are identified applicable files
- If this linter is active, all files linted by all other active linters will be linted
How the linting is performed
cspell is called once on the whole project directory (project CLI lint mode)
- filtering can not be done using MegaLinter configuration variables,it must be done using cspell configuration or ignore file (if existing)
VALIDATE_ALL_CODEBASE: falsedoesn't make cspell analyze only updated files
Example calls
cspell myfile.any
cspell -c cspell.json myfile.any
Help content
Usage: cspell [options] [command]
Spelling Checker for Code
Options:
-V, --version output the version number
-h, --help display help for command
Commands:
lint [options] [globs...] Check spelling
trace [options] [words...] Trace words -- Search for words in the
configuration and dictionaries.
check [options] <files...> Spell check file(s) and display the
result. The full file is displayed in
color.
suggestions|sug [options] [words...] Spelling Suggestions for words.
init [options] Initialize a CSpell configuration file.
link Link dictionaries and other settings to
the cspell global config.
dictionaries [options] List dictionaries
help [command] display help for command
Options for "lint" (the default command):
-c, --config <cspell.json> Configuration file to use. By default cspell
looks for cspell.json in the current directory.
--no-config-search Disable automatic searching for additional
configuration files in parent directories. Only
the specified config file (if any) will be
used.
--stop-config-search-at <dir> Specify a directory at which to stop searching
for configuration files when walking up from
the files being checked. Useful for limiting
config inheritance.
-v, --verbose Display more information about the files being
checked. Add more than one -v for increased
verbosity.
--locale <locale> Set language locales. i.e. "en,fr" for English
and French, or "en-GB" for British English.
--language-id <file-type> Force programming language for unknown
extensions. i.e. "php" or "scala"
--words-only Only output the words not found in the
dictionaries.
-u, --unique Only output the first instance of a word not
found in the dictionaries.
-e, --exclude <glob> Exclude files matching the glob pattern. This
option can be used multiple times to add
multiple globs.
--file-list <path or stdin> Specify a list of files to be spell checked.
The list is filtered against the glob file
patterns. Note: the format is 1 file path per
line.
--file [file...] Specify files to spell check. They are filtered
by the [globs...].
--force-check Force the --file or --file-list documents to be
checked even if it would normally be excluded.
--follow-symlinks Allow checking --file and --file-list documents
referenced by symbolic links.
--no-issues Do not show the spelling errors.
--no-progress Turn off progress messages
--no-summary Turn off summary message in console.
-s, --silent Silent mode, suppress error messages.
--no-exit-code Do not return an exit code if issues are found.
--quiet Only show spelling issues or errors.
--fail-fast Exit after first file with an issue or error.
--continue-on-error Continue processing files even if there is a
configuration error.
-r, --root <root folder> Root directory, defaults to current directory.
--no-relative Issues are displayed with absolute path instead
of relative to the root.
--show-context Show the surrounding text around an issue.
--show-suggestions Show spelling suggestions.
--no-show-suggestions Do not show spelling suggestions or fixes.
--no-must-find-files Do not error if no files are found.
--cache Use cache to only check changed files.
--no-cache Do not use cache.
--cache-reset Reset the cache file.
--cache-strategy <strategy> Strategy to use for detecting changed files.
(choices: "content", "metadata", default:
"content")
--cache-location <path> Path to the cache file or directory. (default:
".cspellcache")
--dot Include files and directories starting with `.`
(period) when matching globs.
--glob-symlinks Follow symbolic links when matching globs.
--gitignore Ignore files matching glob patterns found in
.gitignore files.
--no-gitignore Do NOT use .gitignore files.
--gitignore-root <path> Prevent searching for .gitignore files past
root.
--validate-directives Validate in-document CSpell directives.
--max-file-size <size> Prevent checking large files. i.e 1MB, 50KB,
1GB
--color Force color.
--no-color Turn off color.
--no-default-configuration Do not load the default configuration and
dictionaries.
--dictionary <name> Enable a dictionary by name.
--disable-dictionary <name> Disable a dictionary by name.
--reporter <module|path> Specify one or more reporters to use.
--report <level> Set how unknown words are reported (choices:
"all", "simple", "typos", "flagged")
--issue-template [template] Use a custom issue template. See --help
--issue-template for details.
More Examples:
cspell "**/*.js" --reporter @cspell/cspell-json-reporter
This will spell check all ".js" files recursively and use
"@cspell/cspell-json-reporter".
cspell . --reporter default
This will force the default reporter to be used overriding
any reporters defined in the configuration.
cspell . --reporter ./<path>/reporter.cjs
Use a custom reporter. See API for details.
cspell "*.md" --exclude CHANGELOG.md --files README.md CHANGELOG.md
Spell check only check "README.md" but NOT "CHANGELOG.md".
cspell "/*.md" --no-must-find-files --files $FILES
Only spell check the "/*.md" files in $FILES,
where $FILES is a shell variable containing the list of files.
cspell --help --verbose
Show all options including hidden options.
References:
https://cspell.org
https://github.com/streetsidesoftware/cspell
Installation on mega-linter Docker image
- Dockerfile commands :
# renovate: datasource=npm depName=cspell ARG NPM_CSPELL_VERSION=10.4.0
- NPM packages (node.js):

