Backup & Export Settings

Export your settings, modes, vocabulary, and API keys to a file and restore them on another device or after a reinstall.

HyperWhisper can export your configuration to a file and import it back later — on the same machine, a different one, or across platforms. You choose exactly what the file contains: settings, modes, vocabulary, and optionally API keys or your license key.

Exporting a backup

macOS

1. Open Backup settings

   Go to Settings → Backup.

2. Choose what to include

   Three sections are toggled on by default: Settings, Modes, and Vocabulary. Toggle any off to exclude them.

   Two additional optional items are off by default for security reasons:

   • Include API Keys — embeds your cloud provider API keys in the file.
   • Include License Key — embeds your HyperWhisper license key.

   A warning banner appears if either of those is turned on, reminding you to store the file securely.

   You must have at least one section selected for the Export button to become active.

3. Export

   Click Export. A save dialog opens; choose a name and location. The file is saved as a .json file (for example, HyperWhisper-Backup-YYYY-MM-DD.json). A vocabulary-only export uses the .hwbackup.json extension instead.

Windows

1. Open Backup settings

   Go to Settings → Backup.

2. Choose what to include

   Three sections are checked by default: Settings, Modes, and Vocabulary (the Vocabulary checkbox shows the current word count).

   One additional optional item is unchecked by default: Include API Keys — tick it to embed your cloud provider API keys in the file.

   The Export button becomes inactive if nothing is checked.

3. Export

   Click Export Backup. A save dialog opens with a default file name (HyperWhisper-Backup-YYYY-MM-DD). For a vocabulary-only export the name becomes HyperWhisper Vocabulary YYYY-MM-DD. The file is saved as .hwbackup.json.

API keys and license keys are not included by default. Keep any file that contains them in a secure location — treat it like a password.

Importing a backup

Import is always merge-only: existing data is never wiped. Modes and vocabulary from the file are added to what you already have. Only sections present in the chosen file can be restored, and you can deselect any of them before committing.

macOS

1. Open Backup settings

   Go to Settings → Backup.

2. Pick a file

   Click Import and select a backup file. The open dialog accepts .json files, which covers both the standard full-backup format and vocabulary-only .hwbackup.json files. HyperWhisper reads the file before showing any options.

   If the file is invalid or unreadable, an error is shown and no changes are made.

3. Review what the file contains

   An import sheet slides up showing a summary of what the file holds. For a standard full-backup (.json) the summary may include Settings, Modes, Vocabulary, and API keys. For a vocabulary-only .hwbackup.json file only the Vocabulary section is shown; Settings, Modes, and API keys are not present and cannot be selected. Each section present in the file is checked on; sections absent from the file appear dimmed and cannot be selected.

   Uncheck any section you do not want to restore.

4. Resolve vocabulary conflicts (if applicable)

   If the file contains vocabulary and you have it selected, the sheet shows a pre-merge count: how many words are new (will be added) and how many already exist in your list. If there are conflicts, choose one:

   • Skip — keep your existing entries unchanged (default).
   • Replace — overwrite conflicting entries with the values from the file.

   Words that do not exist in your list are always added regardless of this choice.

5. Confirm

   Click Import. A confirmation shows how many modes and vocabulary items were imported. Nothing changes until you click this button.

Windows

1. Open Backup settings

   Go to Settings → Backup.

2. Pick a file

   Click Choose File and select a .hwbackup.json file. HyperWhisper inspects the file and reveals an import panel below the button.

   If the file is invalid, an error appears inline and no panel is shown.

3. Review what the file contains

   The import panel lists the sections found in the file. Each present section is checked on and enabled; absent sections are unchecked and greyed out.

   Uncheck any section you do not want to restore.

4. Resolve vocabulary conflicts (if applicable)

   When the file contains vocabulary and it is selected, a conflict-resolution option appears:

   • Skip — keep your existing entries unchanged (default; reset to Skip for each newly loaded file).
   • Replace — overwrite conflicting entries with the values from the file.

   If vocabulary is selected, a confirmation dialog appears before import runs, showing how many words will be added and how many conflicts were found.

5. Confirm

   Click Import Selected. The panel closes and a status line confirms how many modes and vocabulary items were imported.

What each section covers

Section	What is backed up
Settings	App preferences (audio input, transcription provider, post-processing, display options, etc.)
Modes	All custom transcription modes you have created
Vocabulary	Your custom word list including replacements
API Keys	Cloud provider API keys (optional — off by default)
License Key	Your HyperWhisper license key (macOS only — optional, off by default)

Vocabulary merge behavior

Vocabulary import never deletes words already in your list.

Incoming word	Result
Not in your list	Added as a new entry
Already in your list (case-insensitive match)	Skipped, or replacement updated — your choice

Cross-platform compatibility

A backup exported on macOS can be imported on Windows, and vice versa. Both platforms use the same universal .hwbackup.json format (schemaVersion: 2).

When importing a backup from the other platform:

• Shared settings (paste behavior, filler words, recording options, etc.) are applied directly.
• Platform-specific settings that have no equivalent on the receiving platform are ignored and preserved for round-trip fidelity — if you later re-export from the original platform, those settings come back.
• Modes are imported using the shared mode fields. Platform-specific mode details (for example, local engine choices on Windows) are preserved across round-trips even if the other platform does not display them.
• Vocabulary is merged by word text (case-insensitive). Cross-platform UUIDs from the originating device do not create duplicates.

A vocabulary-only .hwbackup.json file (containing only the vocabulary key) is the smallest portable format — useful for sharing a word list without bundling settings or modes. A standard legacy macOS full-backup (.json) cannot be imported on Windows because the Windows app requires schemaVersion: 2.

What is not included

• Audio recordings — recording files on disk are never exported.
• Transcription history — past transcripts are stored locally and not included in the backup.

For more on vocabulary and how it affects transcription, see Custom Vocabulary.