> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openwhispr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Choosing a shortcut that works

> The rules a hotkey has to follow, which combinations your system won't give up, and what to use instead.

Most rejected shortcuts fail for one of three reasons: no modifier key, a
combination your operating system has already claimed, or another app got there
first. OpenWhispr tells you which when it refuses.

Set shortcuts under **Settings** → **Hotkeys** under **App**.

## The rules

The app shows these in a **Shortcut Guide** next to the hotkey field:

* **Use at least one modifier** — Ctrl, Alt, Shift, Cmd, or similar.
* **Three keys maximum.** Four-key combinations are rejected.
* **Single keys on their own aren't allowed.** The exception is the macOS Globe
  key, which is handled separately.
* **Reserved system shortcuts are blocked.** Each platform has its own list.
* **Some combinations may still conflict** with whatever else you run — those
  can't be predicted, only tried.

## The one principle worth knowing

**Pick a combination that types nothing.**

A hotkey is held down while you talk, sometimes for a minute, in whatever app
you're already typing into. If it ever slips through — a moment before the app
grabs it, a window that doesn't give it up — a combination ending in a letter
puts that letter in your document. A combination made only of modifier keys
can't.

That single test explains why the defaults are what they are, and it's a better
guide than any list.

## What to use

| Platform    | Best                                                                          | Also good                                                                                    |
| ----------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| **macOS**   | **Globe / Fn** — the default. One key, reachable with a thumb, types nothing. | `Control+Option` (modifiers only). Mouse button 4 or 5, if your mouse has them — macOS only. |
| **Windows** | **Ctrl+Win** — the default. Two modifiers, types nothing.                     | `Ctrl+Alt`, same reasoning. `Ctrl+Shift+K` if you'd rather have a letter.                    |
| **Linux**   | **Ctrl+Super** — the default.                                                 | `Ctrl+Shift+K` or `Ctrl+Shift+J`.                                                            |

In every case **the default is the recommendation.** If dictation is working,
there's no reason to change it — the reasons to change are a physical conflict
with something you use constantly, a keyboard without the key, or wanting the
same shortcut across two machines with different layouts.

<Note>
  Modifier-only combinations like `Ctrl+Win` are fully supported and are what
  the app ships with. You don't need a letter on the end.
</Note>

## What to avoid

* **`Win+H` on Windows** — that's Windows' own voice typing shortcut. Binding it
  puts two dictation systems on one key.
* **`Cmd+Space` on macOS** — Spotlight, and the default for several popular
  launchers besides.
* **Anything ending in a common letter with one modifier** — `Ctrl+S`, `Cmd+F`
  and their neighbours mean something in nearly every app, and most are blocked
  outright.
* **Caps Lock.** Some dictation tools use it; OpenWhispr doesn't support it.

<Warning>
  On **Linux**, three combinations shown in the app's own Shortcut Guide —
  `Super+S`, `Ctrl+Alt+D` and `Alt+Space` — are on the reserved list and will be
  refused when you try to set them. Use the table above instead. We're fixing
  the in-app list.
</Warning>

## What the errors mean

| Message                                                                 | What's happening                                                                                        |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| *"\[key] is already registered by another application"*                 | Something else on your machine claimed it first. Pick another, or quit the other app to find out which. |
| *"\[key] may be reserved by your desktop environment"*                  | Your OS or desktop won't release it. Nothing OpenWhispr can do — choose a different one.                |
| *"Could not register \[key]. It may be in use by another application."* | Same as the first, where the system didn't say who has it.                                              |
| *"Failed to update hotkey to \[key]. Check the format is valid."*       | The combination isn't a shape the app accepts — usually a missing modifier.                             |
| *"This hotkey is already used for \[feature]"*                          | You've assigned it to another OpenWhispr shortcut. Each of the five needs its own.                      |

When a shortcut is rejected the app offers up to three alternatives inline.
They're a fixed per-platform list rather than a check of what's free on your
machine, so treat them as a starting point and not a guarantee.

<Tip>
  If you want a single key with no modifier and you're on a Mac, the Globe/Fn
  key is the one designed to work that way — and it's already your default.
  Everything else needs a modifier.
</Tip>

## If it registers but doesn't do anything

That's a different problem — the shortcut saved fine and something is
intercepting it, or a permission is missing. See [my hotkey doesn't
work](/help/fix/hotkey-not-working).

<Snippet file="still-need-help.mdx" />

## Related

* [Your hotkeys](/help/dictation/hotkeys)
* [Hold or tap](/help/dictation/hold-or-tap)
* [My hotkey doesn't work](/help/fix/hotkey-not-working)