Configure a Global cSpell User Dictionary in VS Code

This article shows how to move your custom cSpell words out of VS Code’s settings.json and into a dedicated global dictionary. This keeps your configuration clean while providing a single, reusable place for technical terms, product names, and other words you use across projects.

When using the Code Spell Checker (cSpell) extension in VS Code, custom words can be added directly to settings.json using cSpell.userWords. Over time, however, this list can become large and clutter the VS Code configuration.

A cleaner approach is to maintain custom words in a separate global dictionary file.

Note: These instructions assume you are using macOS.

Create the Dictionary File

Create a global cSpell dictionary in your home directory:

touch ~/.cspell-dictionary.txt

For a user named username, the full path to the file would be:

/Users/username/.cspell-dictionary.txt

Open the file in VS Code:

code ~/.cspell-dictionary.txt

Add custom words to the dictionary with one word per line:

bootcamp
cfadmin
cfconfig
cfcs
cfdocument
cfengine
cfformat
cfinvoke
cflog
cfoutput
cfpm
cfschedule
cfscript
cfset
cfusion
CommandBox
Fixinator
Flexbox
Glyphicons
labwc
Lucee
LUCEEONLY
Mailpit
mailsent
navbars
Ollama
raspi
strikethrough
Udemy
Webroot
WebUI

Unlike settings.json, the dictionary file does not use JSON syntax. Do not include quotes, commas, or brackets.

Configure cSpell

Open your VS Code settings.json and add the following:

"cSpell.dictionaryDefinitions": [
    {
        "name": "my-words",
        "path": "/Users/username/.cspell-dictionary.txt",
        "addWords": true
    }
],
"cSpell.dictionaries": [
    "my-words"
],

This defines a dictionary named my-words and tells cSpell to use it globally.

The addWords setting allows cSpell to add new words to this dictionary when using its Add Word to Dictionary functionality.

Remove cSpell.userWords

If the same words are currently stored in settings.json:

"cSpell.userWords": [
    "CFML",
    "CommandBox",
    "Fixinator",
    "Lucee",
    "Ollama"
],

copy those words into .cspell-dictionary.txt, then remove the cSpell.userWords setting.

Your custom words will now be maintained in the global dictionary instead of settings.json.

Adding New Words

When cSpell flags a legitimate word such as:

Ollama

use the cSpell quick fix in VS Code and add the word to the my-words dictionary.

Because the dictionary was configured with:

"addWords": true

new words can be written to:

~/.cspell-dictionary.txt

instead of continually expanding cSpell.userWords in settings.json.

The dictionary will gradually grow as new project-specific terminology, product names, acronyms, and technical terms are encountered.

Result

The VS Code configuration remains small:

"cSpell.dictionaryDefinitions": [
    {
        "name": "my-words",
        "path": "/Users/username/.cspell-dictionary.txt",
        "addWords": true
    }
],
"cSpell.dictionaries": [
    "my-words"
],

while the potentially much larger collection of custom words lives separately in:

~/.cspell-dictionary.txt

This keeps settings.json cleaner and provides a single global dictionary that can be maintained independently of VS Code’s other settings.