How to Manage Word Custom Dictionaries Programmatically via VBA

You want to add, remove, or modify custom dictionaries in Word without opening the Options dialog each time. Word stores custom dictionaries as .dic files, and the built-in interface only lets you manage them one at a time. This article explains how to use VBA macros to automate dictionary management, including adding new dictionaries, enabling or disabling them, and listing all installed dictionaries. You will get ready-to-run VBA code and clear explanations for each operation.

How Word Custom Dictionaries Work Under VBA

Word stores spelling exceptions and added words in plain-text files with a .dic extension. These files live in the user’s roaming profile folder by default, typically under %AppData%\Microsoft\UProof. The VBA object model exposes these dictionaries through the CustomDictionaries collection, which is a property of the Languages object. Each dictionary is represented by a Dictionary object. You can add, remove, enable, or disable dictionaries, and you can change which dictionary is the active one for adding new words.

Before writing any macro, you need to enable the VBA editor. Press Alt+F11 to open the Visual Basic Editor. In the menu, go to Tools > References and ensure that the reference to Microsoft Word 16.0 Object Library is checked. This reference is required to access the CustomDictionaries collection. All code examples below should be placed in a standard module, not in a document or template module, to avoid confusion with event handlers.

Step-by-Step VBA Procedures for Dictionary Management

1. List All Active Custom Dictionaries
   This macro prints the name and full path of every dictionary currently loaded in Word. Paste the code into a standard module and run it. The results appear in the Immediate window (Ctrl+G).

   Sub ListCustomDictionaries()
       Dim dic As Dictionary
       For Each dic In Application.CustomDictionaries
           Debug.Print dic.Name & " -- " & dic.Path
       Next dic
   End Sub

2. Add a New Custom Dictionary
   To register a .dic file that already exists on disk, use the Add method. The file must be a plain-text file with one word per line. If the file does not exist, Word creates it automatically when you first add a word to it.

   Sub AddCustomDictionary()
       Dim dicPath As String
       dicPath = "C:\MyDictionaries\TechnicalTerms.dic"
       Application.CustomDictionaries.Add FileName:=dicPath
       MsgBox "Dictionary added: " & dicPath
   End Sub

3. Remove a Custom Dictionary From the Active List
   Removing a dictionary does not delete the .dic file. It only removes the dictionary from Word’s active collection. Use the Delete method on the specific dictionary object.

   Sub RemoveCustomDictionary()
       Dim dic As Dictionary
       Dim dicName As String
       dicName = "TechnicalTerms.dic"
       For Each dic In Application.CustomDictionaries
           If dic.Name = dicName Then
               dic.Delete
               MsgBox "Removed: " & dicName
               Exit For
           End If
       Next dic
   End Sub

4. Set the Active Custom Dictionary for Adding Words
   When you right-click a misspelled word and choose Add to Dictionary, Word adds it to the dictionary specified by the ActiveCustomDictionary property. You can change this target dictionary programmatically.

   Sub SetActiveDictionary()
       Dim dic As Dictionary
       Dim targetName As String
       targetName = "TechnicalTerms.dic"
       For Each dic In Application.CustomDictionaries
           If dic.Name = targetName Then
               Set Application.ActiveCustomDictionary = dic
               MsgBox "Active dictionary set to: " & targetName
               Exit For
           End If
       Next dic
   End Sub

5. Enable or Disable a Custom Dictionary
   Each dictionary has a ReadOnly property that controls whether Word can add words to it. Setting ReadOnly = True effectively disables adding new words while still using the dictionary for spell-check. To fully disable the dictionary for spell-check, set dic.ReadOnly = True and remove it from the active collection temporarily. However, the simplest approach is to set the LanguageSpecific property or remove the dictionary. The code below toggles the read-only state.

   Sub ToggleDictionaryReadOnly()
       Dim dic As Dictionary
       Dim dicName As String
       dicName = "TechnicalTerms.dic"
       For Each dic In Application.CustomDictionaries
           If dic.Name = dicName Then
               dic.ReadOnly = Not dic.ReadOnly
               MsgBox dicName & " read-only set to: " & dic.ReadOnly
               Exit For
           End If
       Next dic
   End Sub

Common Errors and Unexpected Behavior

Run-time error 5174: File not found

This error occurs when the Add method receives a file path that does not exist and the parent folder does not exist. Word cannot create the .dic file if the folder is missing. Before calling Add, verify that the folder exists using the Dir function or CreateObject("Scripting.FileSystemObject"). If the folder is missing, create it first with MkDir.

Dictionary not appearing in the Options dialog after adding

Word caches the dictionary list when the application starts. If you add a dictionary via VBA while Word is running, it appears in the CustomDictionaries collection immediately, but the Options dialog (File > Options > Proofing > Custom Dictionaries) may not refresh until you restart Word. This is a known UI limitation. The dictionary is still active for spell-check even if it does not show in the dialog until restart.

Cannot remove the default custom dictionary

Word ships with a default dictionary named default.dic (or CUSTOM.DIC in older versions). You cannot delete this dictionary using the Delete method. Attempting to do so raises a permission error. If you need to suppress it, set its ReadOnly property to True and do not use it as the active dictionary.

Adding words to a dictionary via VBA does not update spelling immediately

When you add a word to a .dic file directly (by writing to the file), Word does not reload the dictionary until the next spell-check cycle or application restart. To force a reload, you can toggle the dictionary’s ReadOnly property or call Application.CheckSpelling on a dummy string. The cleanest method is to restart the spelling engine by setting Application.CheckLanguageSettings to True for a brief moment, but this is not officially documented. In practice, the simplest workaround is to reopen the document.

VBA Methods vs Manual Options Dialog: Key Differences

Item	VBA Automation	Manual (Options Dialog)
Add a dictionary	Application.CustomDictionaries.Add supports any folder path	Limited to UProof folder by default; requires browsing each time
Remove a dictionary	dic.Delete removes from collection without deleting file	Select dictionary and click Remove; same result
Set active dictionary for adding words	Application.ActiveCustomDictionary = dic changes target instantly	Drop-down list in Custom Dictionaries dialog
List all dictionaries with full paths	One macro prints all paths to Immediate window	Not available; must inspect each dictionary’s properties individually
Bulk add multiple dictionaries	Loop through a list of file paths and call Add for each	Not supported; must add one at a time
Error handling	Requires manual On Error Resume Next or On Error GoTo	Built-in error messages for missing files or permissions

Now you can automate custom dictionary management in Word using VBA. Start by running the list macro to see which dictionaries are currently loaded. Then try adding a new dictionary from a network share or a project-specific folder. For advanced scenarios, combine dictionary management with document event handlers to automatically switch dictionaries based on the document’s subject. One advanced tip: store your custom dictionary paths in a text file or an Excel sheet and read them from VBA to deploy dictionaries across multiple workstations without manual configuration.