> ## 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.

# My hotkey doesn't work

> Nothing happens when you press the shortcut — conflicts, blocked keys, and the per-desktop rules on Linux.

You press your dictation shortcut and nothing happens. Almost always, another
application registered the same combination first — whoever asks the operating
system first wins, and OpenWhispr is told it can't have it.

Every hotkey lives in **Settings** → **Hotkeys** under **App**. That section
holds **Dictation Hotkey** and the separate shortcuts for **Voice Agent**,
**Translation** and **Meeting** recording.

## The defaults

| Platform          | Default dictation hotkey               |
| ----------------- | -------------------------------------- |
| macOS             | the **Globe / Fn** key                 |
| Windows and Linux | **Ctrl** + **Super** (the Windows key) |

If the default can't be registered at startup, OpenWhispr tries **F8**, then
**F9**, then **Ctrl+Shift+Space** — so if your hotkey is one of those and you
never chose it, that's why.

## Quick checks

<Steps>
  <Step title="Try a different combination">
    The fastest way to prove a conflict. Open **Settings** → **Hotkeys** under
    **App**, set **Dictation Hotkey** to something unusual like
    **Ctrl+Shift+K**, and try again. If that works, the original was taken.
  </Step>

  <Step title="Add a second hotkey rather than replacing the first">
    Use **Add another hotkey** to bind a fallback. Both work, so you're covered
    if one is claimed by an application you only sometimes run.
  </Step>

  <Step title="Check the Shortcut Guide">
    The hotkey field shows a **Shortcut Guide** with the rules and recommended
    combinations for your platform. Some keys are refused outright — the app
    lists them under **Blocked shortcuts**, because they're reserved by the
    system.
  </Step>

  <Step title="Check the app you're typing into">
    Full-screen games, remote desktop sessions and virtual machines capture
    keyboard input before anything else sees it. Test in a plain text editor to
    rule this out.
  </Step>
</Steps>

## What makes a valid shortcut

The app enforces these, so a combination that breaks them won't save:

* It must include at least one modifier — Ctrl, Alt, Shift and so on.
* Three keys maximum.
* Single keys on their own aren't allowed.
* Reserved system shortcuts are refused.

Combinations that work well, by platform:

* **macOS** — Globe/Fn (the default), `Control+Option`, `Ctrl+Shift+K`
* **Windows** — Ctrl+Win (the default), `Ctrl+Alt`, `Ctrl+Shift+K`
* **Linux** — Ctrl+Super (the default), `Ctrl+Shift+K`, `Ctrl+Shift+J`

<Warning>
  On **Linux**, three combinations the app's own Shortcut Guide suggests —
  `Super+S`, `Ctrl+Alt+D` and `Alt+Space` — are on its reserved list and will be
  refused. Use the ones above instead.
</Warning>

The best choices are the ones that type nothing if they slip through while
you're holding them — the platform defaults are all modifier-only or the Globe
key for exactly that reason.

## Tap or hold

**Activation Mode** in the same section decides how the key behaves:

* **Tap** — press once to start, press again to stop.
* **Hold** — hold the key while you speak, release to finish.

If dictation stops the instant you start speaking, or never stops, you're
probably in the other mode from the one you expect.

<Warning>
  **Hold on Linux needs one-time setup.** Reading key-down and key-up events
  requires access to input devices. The app tells you so — *"Hold to Speak needs
  extra setup"* — and gives you the command:
  `sudo usermod -aG input $USER`. Log out and back in afterwards.
</Warning>

## Linux desktops

<Tabs>
  <Tab title="GNOME (Wayland)">
    GNOME doesn't let applications grab global shortcuts, so OpenWhispr
    registers native GNOME shortcuts instead. Check **Settings → Keyboard →
    Keyboard Shortcuts** for a conflict with an existing binding.

    GNOME also requires a regular key rather than a modifier-only combination,
    which is why F8 is the usual fallback there.
  </Tab>

  <Tab title="Hyprland">
    OpenWhispr writes its binds into your Hyprland config, so `hyprctl` must be
    on your PATH.

    Two things to know. First, OpenWhispr **claims** the combination you choose —
    any existing Hyprland bind on the same keys is unbound when it registers.
    Second, if the app can't write to your config file it warns that *"Hyprland
    keybinds will not persist"*: they work now but won't survive a config
    reload. Make sure the file exists and is writable.
  </Tab>

  <Tab title="KDE">
    KDE reports why a registration failed — either the combination is already
    taken, or it's a modifier-only shortcut the system reserves. Pick a
    combination with a regular key in it.
  </Tab>
</Tabs>

## FAQ

<AccordionGroup>
  <Accordion title="It worked, then stopped after I opened another app.">
    That app claimed the shortcut. Close it and try again to confirm, then
    either change one of the two or add a second hotkey in OpenWhispr.
  </Accordion>

  <Accordion title="It says 'Failed to register hotkey'.">
    The operating system refused the combination — usually because it's already
    taken or it's reserved. Choose another; the Shortcut Guide lists ones that
    work.
  </Accordion>

  <Accordion title="My hotkey changed on its own.">
    If the one you set couldn't be registered at startup, OpenWhispr falls back
    to F8, F9 or Ctrl+Shift+Space so dictation still works. Set it again and, if
    it keeps happening, something else is taking it first.
  </Accordion>

  <Accordion title="The Globe key does nothing on macOS.">
    Check that macOS isn't using it itself — **System Settings → Keyboard**,
    where the **Press Globe key to** option can be set to change input source or
    show emoji.
  </Accordion>
</AccordionGroup>

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

## Related

* [Choosing a shortcut that works](/help/dictation/choosing-a-shortcut)
* [Your hotkeys](/help/dictation/hotkeys)
* [How dictation works](/guides/dictation)
* [It answers me instead of typing](/help/fix/it-answers-instead-of-typing)
* [Clipboard and system audio on Linux](/help/fix/linux-clipboard-and-audio)