{"id":3051,"date":"2026-08-19T18:05:06","date_gmt":"2026-08-19T22:05:06","guid":{"rendered":"https:\/\/csimmons.dev\/blog\/?p=3051"},"modified":"2026-08-19T18:13:37","modified_gmt":"2026-08-19T22:13:37","slug":"configure-a-global-cspell-user-dictionary-in-vs-code","status":"publish","type":"post","link":"https:\/\/csimmons.dev\/blog\/2026\/08\/configure-a-global-cspell-user-dictionary-in-vs-code\/","title":{"rendered":"Configure a Global cSpell User Dictionary in VS Code"},"content":{"rendered":"

This article shows how to move your custom cSpell words out of VS Code\u2019s settings.json<\/code> 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.<\/p>\n

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

A cleaner approach is to maintain custom words in a separate global dictionary file.<\/p>\n

\n Note:<\/strong> These instructions assume you are using macOS.\n<\/p><\/blockquote>\n

Create the Dictionary File<\/h2>\n

Create a global cSpell dictionary in your home directory:<\/p>\n

touch ~\/.cspell-dictionary.txt\n<\/code><\/pre>\n
For a user named username<\/code>, the full path to the file would be:<\/p>\n
\/Users\/username\/.cspell-dictionary.txt\n<\/code><\/pre>\n
Open the file in VS Code:<\/p>\n
code ~\/.cspell-dictionary.txt\n<\/code><\/pre>\n
Add custom words to the dictionary with one word per line<\/strong>:<\/p>\n
bootcamp\ncfadmin\ncfconfig\ncfcs\ncfdocument\ncfengine\ncfformat\ncfinvoke\ncflog\ncfoutput\ncfpm\ncfschedule\ncfscript\ncfset\ncfusion\nCommandBox\nFixinator\nFlexbox\nGlyphicons\nlabwc\nLucee\nLUCEEONLY\nMailpit\nmailsent\nnavbars\nOllama\nraspi\nstrikethrough\nUdemy\nWebroot\nWebUI\n<\/code><\/pre>\n
Unlike settings.json<\/code>, the dictionary file does not use JSON syntax. Do not include quotes, commas, or brackets.<\/p>\n
Configure cSpell<\/h2>\n
Open your VS Code settings.json<\/code> and add the following:<\/p>\n
\"cSpell.dictionaryDefinitions\": [\n    {\n        \"name\": \"my-words\",\n        \"path\": \"\/Users\/username\/.cspell-dictionary.txt\",\n        \"addWords\": true\n    }\n],\n\"cSpell.dictionaries\": [\n    \"my-words\"\n],\n<\/code><\/pre>\n
This defines a dictionary named my-words<\/code> and tells cSpell to use it globally.<\/p>\n
The addWords<\/code> setting allows cSpell to add new words to this dictionary when using its Add Word to Dictionary<\/strong> functionality.<\/p>\n
Remove cSpell.userWords<\/code><\/h2>\n
If the same words are currently stored in settings.json<\/code>:<\/p>\n
\"cSpell.userWords\": [\n    \"CFML\",\n    \"CommandBox\",\n    \"Fixinator\",\n    \"Lucee\",\n    \"Ollama\"\n],\n<\/code><\/pre>\n
copy those words into .cspell-dictionary.txt<\/code>, then remove the cSpell.userWords<\/code> setting.<\/p>\n
Your custom words will now be maintained in the global dictionary instead of settings.json<\/code>.<\/p>\n
Adding New Words<\/h2>\n
When cSpell flags a legitimate word such as:<\/p>\n
Ollama\n<\/code><\/pre>\n
use the cSpell quick fix in VS Code and add the word to the my-words<\/code> dictionary.<\/p>\n
Because the dictionary was configured with:<\/p>\n
\"addWords\": true\n<\/code><\/pre>\n
new words can be written to:<\/p>\n
~\/.cspell-dictionary.txt\n<\/code><\/pre>\n
instead of continually expanding cSpell.userWords<\/code> in settings.json<\/code>.<\/p>\n
The dictionary will gradually grow as new project-specific terminology, product names, acronyms, and technical terms are encountered.<\/p>\n
Result<\/h2>\n
The VS Code configuration remains small:<\/p>\n
\"cSpell.dictionaryDefinitions\": [\n    {\n        \"name\": \"my-words\",\n        \"path\": \"\/Users\/username\/.cspell-dictionary.txt\",\n        \"addWords\": true\n    }\n],\n\"cSpell.dictionaries\": [\n    \"my-words\"\n],\n<\/code><\/pre>\n
while the potentially much larger collection of custom words lives separately in:<\/p>\n
~\/.cspell-dictionary.txt\n<\/code><\/pre>\n
This keeps settings.json<\/code> cleaner and provides a single global dictionary that can be maintained independently of VS Code’s other settings.<\/p>\n","protected":false},"excerpt":{"rendered":"
This article shows how to move your custom cSpell words out of VS Code\u2019s 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, … Read more<\/a><\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_exactmetrics_skip_tracking":false,"_cloudinary_featured_overwrite":false,"_jetpack_newsletter_access":"","_jetpack_dont_email_post_to_subs":false,"_jetpack_newsletter_tier_id":0,"_jetpack_memberships_contains_paywalled_content":false,"_jetpack_memberships_contains_paid_content":false,"footnotes":""},"categories":[68],"tags":[12,53],"class_list":["post-3051","post","type-post","status-publish","format-standard","hentry","category-developer","tag-developer","tag-vscode"],"jetpack_shortlink":"https:\/\/wp.me\/pbVg43-Nd","jetpack_sharing_enabled":true,"jetpack_featured_media_url":"","_links":{"self":[{"href":"https:\/\/csimmons.dev\/blog\/wp-json\/wp\/v2\/posts\/3051","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/csimmons.dev\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/csimmons.dev\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/csimmons.dev\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/csimmons.dev\/blog\/wp-json\/wp\/v2\/comments?post=3051"}],"version-history":[{"count":2,"href":"https:\/\/csimmons.dev\/blog\/wp-json\/wp\/v2\/posts\/3051\/revisions"}],"predecessor-version":[{"id":3053,"href":"https:\/\/csimmons.dev\/blog\/wp-json\/wp\/v2\/posts\/3051\/revisions\/3053"}],"wp:attachment":[{"href":"https:\/\/csimmons.dev\/blog\/wp-json\/wp\/v2\/media?parent=3051"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/csimmons.dev\/blog\/wp-json\/wp\/v2\/categories?post=3051"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/csimmons.dev\/blog\/wp-json\/wp\/v2\/tags?post=3051"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}