# How to set up Walkie on Linux

> Install Walkie on Arch, Omarchy, Debian or any distro, give it a hotkey on Wayland, and add the Omarchy status bar widget.

Install Walkie from the AppImage, the .deb, or Walkie's own pacman repository on Arch-based systems. The one step that differs from macOS and Windows is the hotkey: Wayland does not let applications listen for global shortcuts, so you bind a key in your compositor to `walkie --start-transcription` and `walkie --stop-transcription` instead. Everything else — dictation, meetings, Read Aloud — works the same as on any other platform.

*Category: Getting started · Last updated: 2026-09-01*

---

> **Important:** The Linux build is experimental and unsigned. Hotkeys, text injection and meeting audio all behave differently from one desktop environment to the next. If something breaks, send it to us from **Settings → About → Send to Support** — that attaches the logs we need.

> **Note:** **On Omarchy?** Every step below works, but Omarchy has its own way of doing two of them — keybindings go through its `o.bind` Lua helper, and it ships a Walkie bar widget. Follow [Walkie on Omarchy](/docs/getting-started/walkie-on-omarchy) instead.

## Which package to use

| Format | Best for | Updates |
| --- | --- | --- |
| **`.AppImage`** | Any distro. No install step — mark it executable and run it. | Re-download |
| **`.deb`** | Debian, Ubuntu and derivatives. | Re-download |
| **pacman package** | Arch, Omarchy, Manjaro, EndeavourOS. | `pacman -Syu` |

All three are on the [download page](https://trywalkie.com/#download). The Arch package is the only one that updates itself, because it comes from a repository.

## Install on Arch, Omarchy or Manjaro

Add Walkie's package repository once, then install and update with pacman like any other package.

```ini
# /etc/pacman.conf
[walkie]
SigLevel = Optional TrustAll
Server = https://b150.s3.us-east-1.amazonaws.com/walkie/arch/$arch
```

```bash
sudo pacman -Syu walkie-bin
```

> **Note:** The repository is unsigned today, which is what `SigLevel = Optional TrustAll` allows. If you would rather verify signatures, use the AppImage instead until package signing ships.

### Install on Debian or Ubuntu

```bash
sudo apt install ./Walkie_*_amd64.deb
```

### Run the AppImage

```bash
chmod +x Walkie_*.AppImage
./Walkie_*.AppImage
```

## Give Walkie a hotkey on Wayland

This is the one part of Linux setup that has no equivalent on macOS or Windows. Wayland has no protocol that lets an application listen for a global keyboard shortcut, so Walkie's in-app shortcut setting cannot see your keypress. Your compositor has to do it instead, and run a Walkie command when the key goes down and up.

> **Note:** On X11 the in-app shortcut works normally — you can skip this section. Walkie tells you which case you are in: if it cannot register a hotkey, it shows a notice in the app with these instructions.

### Hyprland 0.55 and newer

Add to `~/.config/hypr/hyprland.lua`:

```lua
hl.bind("SUPER + CTRL + X", hl.dsp.exec_cmd("walkie --toggle-transcription"))
hl.bind("F9", hl.dsp.exec_cmd("walkie --start-transcription"))
hl.bind("F9", hl.dsp.exec_cmd("walkie --stop-transcription"), { release = true })
```

### Hyprland 0.54 and older

Add to `~/.config/hypr/hyprland.conf`:

```ini
bind  = SUPER CTRL, X, exec, walkie --toggle-transcription
bind  = , F9, exec, walkie --start-transcription
bindr = , F9, exec, walkie --stop-transcription
```

### Sway

```ini
bindsym --no-repeat F9 exec walkie --start-transcription
bindsym --release F9 exec walkie --stop-transcription
```

### GNOME and KDE

Both let you add a custom shortcut in their settings, but neither can bind a key *release*, so you get press-to-toggle rather than push-to-talk. Point the shortcut at:

```bash
walkie --toggle-transcription
```

For real push-to-talk on those desktops, switch Walkie's keyboard backend to **evdev** in Settings, which reads the keyboard directly. It needs your user to be in the `input` group:

```bash
sudo usermod -aG input $USER   # then log out and back in
```

> **Tip:** Push-to-talk — hold to speak, release to transcribe — is worth the extra setup. It is faster than toggling and there is no way to leave the microphone running by accident.

## Text injection

Walkie types your transcription into whatever app has focus, using whichever tool your session supports. Install the one that matches your setup:

| Session | Install | Notes |
| --- | --- | --- |
| **Wayland (Hyprland, Sway)** | `wtype` | Recommended |
| **Wayland (GNOME, KDE)** | `dotool` | Needs the `input` group |
| **X11** | `xdotool` | — |
| **Fallback** | `ydotool` | Needs the `ydotoold` daemon |

Also install `wl-clipboard` so clipboard-based pasting works. On Arch the package install pulls these in as optional dependencies; on other distros install them yourself.

## Meeting audio

To record the other side of a call, Walkie reads your speakers' monitor source through PipeWire's PulseAudio layer. Install:

```bash
sudo pacman -S pipewire-pulse libpulse pipewire-alsa
```

- `pipewire-pulse` and `libpulse` provide the monitor source Walkie records from.
- `pipewire-alsa` is what lets your **microphone** work at all — without it, recording fails with a device error.

> **Note:** Without these, meetings still record your microphone; you just will not hear the other participants in the transcript.

## The Omarchy bar widget

On Omarchy, Walkie can live in your bar: it shows whether Walkie is idle, recording, transcribing or in a meeting, and clicking it starts dictation. The widget ships inside the `walkie-bin` package — see [Walkie on Omarchy](/docs/getting-started/walkie-on-omarchy#add-the-walkie-bar-widget) for how to install and configure it.

## Other status bars

The widget is a thin wrapper around a command you can call from any bar. `walkie status` prints one line of Waybar-shaped JSON and exits; `walkie status --watch` streams a line every time the state changes.

```json
{"text":"<glyph>","alt":"recording","class":"recording","tooltip":"Walkie — recording"}
```

`text` is a Nerd Font icon you can ignore in favour of your own. `class` carries the state: `idle`, `recording`, `analyzing`, `transcribing`, `thinking`, `speaking`, `error`, `meeting`, or `stopped` when Walkie is not running. For Waybar:

```json
"custom/walkie": {
  "exec": "walkie status --watch",
  "return-type": "json",
  "format": "{}",
  "tooltip": true,
  "on-click": "walkie --toggle-transcription"
}
```

## Start Walkie on login

Hyprland ignores the XDG autostart entry Walkie writes, so use its systemd user service instead. The package installs the unit; enable it once:

```bash
systemctl --user enable --now walkie
```

Or, if you would rather keep it in your compositor config:

```ini
exec-once = walkie --start-hidden
```

## Known limitations

- **The recording overlay is off by default.** Some compositors treat it as the focused window, which stops Walkie pasting back into the app you were typing in. You can turn it on in Settings if yours behaves.
- **Builds are unsigned.** Your desktop may warn on first launch.
- **Read Aloud's text capture is limited on Wayland.** Reading a selection from another app does not work on every compositor yet; dropping a file onto Walkie always does.

## Frequently asked questions about how to set up Walkie on Linux

### Why does my hotkey work in some apps but not others?

That is usually text injection rather than the hotkey. If the shortcut starts a recording but nothing is typed, install `wtype` (Wayland) or `xdotool` (X11) — see [Text injection](#text-injection).

### Why does the bar widget say Walkie is not running when it is?

The widget calls `walkie` on your `PATH`. If you installed the AppImage, or you are running a build from source, set the widget's `command` setting to the full path of the binary.

### Do I need to be in the `input` group?

Only if you use the evdev keyboard backend, or `dotool` for typing. Binding keys in your compositor — the recommended setup on Hyprland and Sway — needs no special permissions.

### Does dictation still run on-device?

Yes. On-Device Mode behaves exactly as it does on macOS and Windows: audio never leaves your machine. See [What leaves your device](/docs/privacy-and-security/what-leaves-your-device).

---

Source: https://trywalkie.com/en/docs/getting-started/walkie-on-linux
Walkie help center: https://trywalkie.com/en/docs