Current version: 1.4.1.
NVDA Sync is a portable Windows utility for keeping NVDA folders aligned. Choose one primary NVDA folder and up to five secondary folders. The primary folder is the source of truth; selected components are copied from it to each secondary.
The intended use is to keep an installed NVDA profile and one or more portable NVDA copies in step without manually copying add-ons, gestures, dictionaries, profiles, or other configuration files after every update.
Project page: https://github.com/OnjLouis/NVDASync.
E:\nvda, F:\nvda, or their userConfig folders.| Menu | Commands |
|---|---|
| Folders | Set or detect the primary folder, add a secondary folder, edit the selected secondary folder, open properties for the selected secondary folder, remove the selected secondary folder, validate the current configuration, clean up orphaned INI sections in nvda.ini or gestures.ini, and manage speech dictionary entries. |
| Add-ons | Export an add-on pack from the primary folder, or install local add-ons into configured secondary folders. |
| Options | Open Preferences, save the visible log, minimise to the notification area, and exit. |
| Help | Open this manual, check for updates, open the GitHub project page, contact Andre, donate, and show About. |
The main window stays focused on the primary folder, secondary folders, sync controls, and log output. Folder management is also available from the secondary-folder context menu.
Preferences changes apply immediately and are saved beside the app.
| Tab | Settings |
|---|---|
| Sync | Choose which NVDA components are synced, choose the default add-on mode, choose whether portable NVDA program files are updated, choose whether program updates create ZIP backups, enable or disable primary-folder watching, read the watch timing, and choose whether stale items are deleted from secondary folders. |
| Files | Choose whether Python cache files are excluded. This is on by default. |
| Startup and updates | Choose whether NVDA Sync runs when Windows starts, whether it starts minimised to the notification area, how often it checks GitHub releases, and whether automatic checks may install updates silently when possible. |
| Component | What It Syncs | Default |
|---|---|---|
| Add-ons | The addons folder. |
On |
| Input gestures | gestures.ini. |
Off |
| NVDA.ini | nvda.ini. This can include machine-specific settings, so enable it deliberately. |
Off |
| Speech dictionaries | The speechDicts folder. |
Off |
| Configuration profiles | The profiles folder and profileTriggers.ini, so automatic profile triggers travel with the profiles they activate. |
Off |
| Other root configuration files | Other files stored directly in the NVDA configuration folder. Known components such as nvda.ini, gestures.ini, and profileTriggers.ini are not included here because they have their own entries. |
Off |
| Other root configuration folders | Other folders stored directly in the NVDA configuration folder, such as add-on data folders. Known components such as addons, profiles, and speechDicts are not included here because they have their own entries. |
Off |
| Portable NVDA program files | Updates the application files in a portable NVDA folder from the installed NVDA program folder. The target must be a portable copy with nvda.exe and userConfig. |
Off |
Each secondary folder can use the global defaults from Preferences or override them. Select a secondary folder and press Enter, double-click it, or choose Properties from the context menu to edit that target.
Per-folder properties are useful when one portable copy should receive every add-on, another should update only add-ons that are already installed there, and another should receive dictionaries or gestures but not add-ons.
The add-on mode choices are: sync all add-ons, update existing add-ons only, or do not sync add-ons. Existing-only mode updates matching add-on folders already present in the secondary, leaves target-only add-ons alone, and does not add new add-ons from the primary.
When portable NVDA program-file updates are enabled for a secondary, NVDA Sync updates the portable copy from the installed NVDA program folder. Before replacing files, it can create a ZIP backup beside the portable folder named like nvda20260619-143000.zip. Backups are enabled by default and can be turned off globally or per secondary folder. The backup excludes userConfig, Settings, Logs, and Backups.
Program-file updates first compare the installed NVDA program folder with the portable target. If nothing differs, no backup is created and no files are touched. They also refuse installed NVDA under Program Files, refuse folder pairs that contain each other, and refuse to update a portable copy while that copy of NVDA is running.
The Folders menu includes Clean up orphaned INI sections, with tools for moving, copying, or deleting whole top-level sections from nvda.ini and gestures.ini. The nvda.ini tool is intended for cases where an add-on has been removed but its configuration section is still present. The gestures.ini tool is intended for gesture sections left behind by add-ons or profiles.
Choose the NVDA data folder to inspect. The nvda.ini tool lists top-level sections such as [addonName]; nested subsections such as [[profile]] remain attached to their parent section and are moved or deleted with it. The gestures.ini file uses flat top-level sections only, so each listed section is handled as a single block.
Gesture lines are preserved exactly as written. For example, None = kb:h means NVDA has explicitly unbound that gesture, and values such as script_jump = kb:a, kb:b keep their comma-separated bindings. NVDA Sync does not automatically delete related sections from the other INI file; some names may look related without being safe to remove together, so users choose what to clean in each file deliberately.
Deleting selected sections always asks for confirmation. Copying selected sections writes them into a configured secondary folder's matching INI file and leaves the source unchanged. Moving selected sections writes them into the destination and then deletes them from the source. Matching destination sections are replaced only after warning you. Content before the first top-level section is preserved and is not selectable.
Before NVDA Sync rewrites an existing INI file, it creates a backup beside it named from the original file, such as nvda20260620-083000.ini or gestures20260620-083000.ini. If the selected file belongs to a running NVDA copy, NVDA Sync warns that NVDA may overwrite the change from memory and offers to close NVDA, apply the edit, and relaunch NVDA afterward.
The Folders menu includes Manage speech dictionary entries. This tool is for cases where whole-folder speech dictionary sync is too broad and you only want to work with one dictionary file or a selected group of pronunciation rules.
Choose a source NVDA folder, then choose one of its speech dictionaries. NVDA Sync lists the default dictionary, current voice dictionaries under speechDicts\voiceDicts.v1, and older flat voice dictionary files directly under speechDicts when they exist.
The entry list uses normal multi-select behavior. Use Shift+arrow or Shift+click for a range, Ctrl+click for scattered entries, or Ctrl+A to select all entries in the list.
| Action | What It Does | Notes |
|---|---|---|
| Sync whole dictionary | Replaces the destination dictionary with the selected source dictionary. | This is whole-file sync for one dictionary. A backup is created beside an existing destination dictionary before it is replaced. |
| Import .dic file | Imports an NVDA speech dictionary file into a chosen NVDA folder. | After choosing the source .dic file, choose the target NVDA folder from your configured folders or browse to another one. default.dic is imported as the default dictionary. Files already arranged under speechDicts keep their relative location. Standalone files named like synth-voice.dic are imported as current voice dictionaries under speechDicts\voiceDicts.v1\synth. Other .dic files are imported as legacy voice dictionaries directly under speechDicts. |
| Delete selected | Removes the selected entries from the source dictionary. | A backup is created beside the source dictionary before it is changed. |
| Copy selected | Appends the selected entries to the destination dictionary. | The source dictionary is unchanged. Duplicate patterns are allowed because NVDA dictionaries can legitimately contain overlapping entries. |
| Move selected | Appends the selected entries to the destination dictionary, then removes them from the source dictionary. | Destination writes happen before source removal so a failed destination write does not lose source entries. |
Comments in NVDA speech dictionary files are attached to the entry that follows them, so a selected entry carries its comment with it. NVDA Sync preserves entry pattern, replacement, case-sensitive flag, and type number as raw dictionary data; it does not reinterpret or remap entry type numbers.
Speech dictionaries are written in NVDA's dictionary format with a UTF-8 byte-order mark and Windows line endings. Before NVDA Sync rewrites an existing dictionary, it creates a timestamped backup beside it. If a dictionary belongs to a running NVDA copy, NVDA Sync warns that NVDA may overwrite the change from memory and offers to close NVDA, apply the edit, and relaunch NVDA afterward.
The Add-ons menu contains tools for preparing or filling secondary NVDA copies without changing the running primary copy.
| Command | What It Does | Safety Notes |
|---|---|---|
| Export add-on pack | Reads the primary addons folder and writes a JSON pack file containing add-on names, summaries, versions, authors, descriptions, and installed folder names. |
The export is metadata only. It does not include add-on code or personal configuration data. |
| Install local add-ons to secondary folders | Reads a folder containing unpacked add-on folders and/or .nvda-addon files, validates each root manifest.ini, and installs valid add-ons into the configured secondary folders. |
The primary folder is never an install target. Existing add-ons with the same manifest name in a secondary folder are replaced. Unavailable removable drives are skipped quietly and reported in the log. |
Local add-on install is intended for portable or otherwise offline NVDA folders. It does not download add-ons, contact the NVDA Add-on Store, or install into a running NVDA profile.
When Python cache exclusion is enabled in Preferences, local installs also skip __pycache__, .pyc, and .pyo files while copying unpacked add-on folders.
The app performs one-way sync only. The primary folder pushes to the configured secondary folders. It does not merge changes back from secondary folders.
Files that are missing or different in a secondary folder are copied from the primary folder. File replacement is staged through a temporary file before the destination is replaced.
When Delete stale items from secondary folders is enabled, files and folders that exist only in a selected secondary component are removed so the secondary matches the primary for that component.
Exclude Python cache files is enabled by default. This skips __pycache__ folders, .pyc files, and .pyo files while copying. When stale deletion is enabled, existing Python cache files in secondary folders are removed. NVDA and add-ons can rebuild those files when needed, and excluding them avoids wasting space on removable drives with large cluster sizes.
Auto-sync uses file-system change events from the primary folder and waits 1.5 seconds after the last change before syncing. Sync work runs in the background so the window and assistive technology remain responsive while larger folders are being mirrored. Use Cancel sync if you need to stop the current run.
If a secondary folder is on a removable drive that is not currently connected, the app skips that folder without showing a disruptive error. While auto-sync is enabled, unavailable secondary folders are checked again every 60 seconds and synced after they become available.
The notification area tooltip reports the current state, such as ready, watching, syncing, waiting for a drive, or finished with errors.
The app refuses to sync when the primary and secondary are the same folder, or when one folder contains the other.
The primary folder is shown as a read-only list item rather than an editable text field, which avoids accidental path changes. Use Browse to choose a folder manually, or Detect to scan likely user-profile locations for an NVDA configuration folder.
You can choose an NVDA folder, a portable NVDA folder, an NVDA configuration folder, or one of the known component folders such as addons, speechDicts, or profiles. This is useful when a user knows where a portable NVDA copy lives but does not know the internal configuration path.
Common layouts resolved by the app include:
<installed profile>\addons<portable NVDA folder>\userConfig<portable NVDA folder>\userConfig\addonsIf more than one NVDA configuration folder is found under a selected parent folder, the app refuses to guess. Choose the intended folder directly.
| Action | Default Hotkey | Scope |
|---|---|---|
| Open the Folders menu. | Alt+F | Main window |
| Open the Add-ons menu. | Alt+A | Main window |
| Open the Options menu. | Alt+O | Main window |
| Open the Help menu. | Alt+H | Main window |
| Move to the primary folder field. | Alt+P | Main window |
| Browse for the primary folder. | Alt+B | Main window |
| Detect the primary folder. | Alt+D | Main window |
| Start a sync now. | Alt+S | Main window |
| Cancel the current sync or local add-on install. | Alt+C | Main window |
| Validate the configured folders and components. | Alt+V | Main window |
| Minimise the app to the notification area. | Alt+N | Main window |
| Open Preferences. | Ctrl+comma | Main window |
| Open properties for the selected secondary folder. | Enter | Secondary folders list |
| Remove the selected secondary folder. | Delete | Secondary folders list |
| Open this manual. | F1 | Main window |
| Check GitHub releases for updates. | Shift+F1 | Main window |
| Open the GitHub project page. | Ctrl+F1 | Main window |
| Switch Preferences tabs. | Ctrl+1 through Ctrl+3 | Preferences |
| Hide the app to the notification area. | Escape | Main window |
| Exit the app. | Alt+F4 | Main window |
| Show the app from the notification area. | Enter on the tray icon, or double-click the tray icon | Notification area |
Command-line switches are useful for testing, shortcuts, and scripted syncs. Running-instance commands only control a copy of the app launched from the same folder.
Normal GUI launches are single-instance across NVDA Sync copies. If another copy is already running from the same folder, the new launch shows the existing window. If another copy is running from a different folder, the new launch asks the older copy to close and then takes over, which prevents two background watchers from syncing the same folders at once.
| Command | Effect |
|---|---|
NVDASync.exe --show | Show the running app from the same folder. |
NVDASync.exe --close | Close the running app from the same folder. |
NVDASync.exe --sync-running | Ask the running app from the same folder to sync now. |
NVDASync.exe --startup-minimized | Start quietly in the notification area. The Windows startup option uses this automatically. |
NVDASync.exe --sync | Run one sync without showing the window, using saved settings unless folders or components are supplied on the command line. |
NVDASync.exe --primary "folder" | Set the primary NVDA or configuration folder for --sync. |
NVDASync.exe --secondary "folder" | Add a secondary NVDA or configuration folder for --sync. This switch may be repeated up to five times. |
NVDASync.exe --delete-stale | Delete stale files and folders from selected secondary components during --sync. |
NVDASync.exe --no-delete-stale | Do not delete stale files and folders during --sync. |
NVDASync.exe --component "id" | Sync one component. May be repeated. IDs are addons, inputGestures, nvdaIni, speechDictionaries, configProfiles, otherConfigFiles, and otherConfigFolders. |
NVDASync.exe --all-components | Sync every supported component. |
NVDASync.exe --export-addon-pack "file" | Export installed add-on metadata from the primary folder. Use --primary to override the saved primary folder. |
NVDASync.exe --install-addons "folder" | Install local add-ons from a folder into secondary folders only. Use one or more --secondary switches to override saved secondary folders. |
NVDASync.exe --exclude-python-cache | Skip __pycache__, .pyc, and .pyo files. |
NVDASync.exe --include-python-cache | Copy Python cache files. |
NVDASync.exe --save | Save command-line folder choices, components, and options back to the app settings. |
NVDASync.exe --apply-update ... | Internal updater command used by NVDA Sync when installing a GitHub release ZIP. |
NVDASync.exe --version | Show version information. |
NVDASync.exe --help | Show command-line help. |
| File or Folder | Purpose |
|---|---|
NVDASync.exe | The application. |
Manual.html | This manual. |
LICENSE.txt | The application license. |
Settings\settings.json | Settings saved beside the app. Moving the app folder moves its settings with it. |
Logs\NVDASync.log | Rolling app log. It is created automatically and rotated to NVDASync.old.log when it grows large. |
Logs\Update.log | Updater progress log. |
Logs\Updater.log | Updater error log, created only when an update fails. |
NVDA Sync writes a rolling log beside the app in Logs\NVDASync.log. Use Options > Save log to save the visible output to a chosen text file for support.
Use Help > Check for updates or Shift+F1 to check GitHub releases at https://github.com/OnjLouis/NVDASync. If a newer release includes a ZIP package, NVDA Sync can download it, close, replace the files in the current folder while preserving Settings, Logs, and Backups, then restart.
Use Preferences > Startup and updates to choose whether NVDA Sync checks for updates never, at startup, hourly, or daily. New installations check at startup by default so users hear about fixes without opening Preferences first. If Install updates silently when possible is enabled, automatic checks can install a newer ZIP release without prompting. Manual update checks still show the normal update dialog.
When NVDA Sync starts, it also asks Windows to keep the current executable path promoted in the notification area. This helps the tray icon remain available after portable updates or folder moves.
.dic files. After choosing the source file, NVDA Sync asks for the target NVDA folder explicitly, infers the dictionary location from the file name and any existing speechDicts folder structure, then imports through the same backup and live-NVDA warning flow as other dictionary operations.# characters, and raw entry type numbers.profileTriggers.ini, so application and other automatic profile triggers are copied with the profiles they activate. Closes issue #5.profileTriggers.ini is no longer treated as an unrelated root configuration file by the generic root-file sync option.gestures.ini section cleanup tool for moving, copying, or deleting orphaned input gesture sections using the same workflow as the existing nvda.ini cleanup tool. Closes issue #3.nvdaYYYYMMDD-HHMMSS.ini or gesturesYYYYMMDD-HHMMSS.ini.nvda.ini and gestures.ini cleanup tools under one Folders-menu INI cleanup submenu, normalised secondary-folder wording, and made startup update checks the default for new installations.nvda.ini location picker for the primary folder, secondary folders, and custom folders.nvdaYYYYMMDD-HHMMSS.ini backups before existing NVDA.ini files are rewritten.NVDASync.exe, while preserving update compatibility for older builds..nvda-addon files.nvda.ini, speech dictionaries, configuration profiles, other root configuration files, and other root configuration folders.NVDA Sync is licensed under the MIT License. See LICENSE.txt.
Created by Codex. Idea, testing, and release direction by Andre Louis.
NVDA Sync is built with Microsoft .NET Framework and Windows Forms.
Questions and feedback can be sent through https://onj.me/contact.
NVDA Sync is free software. If you want to support Andre's work, visit https://www.paypal.me/AndreLouis.