---
title: "WezTerm Key Bindings"
aliases: [wezterm-keys, wezterm-keybindings-config, wezterm-leader-key]
tags: [wezterm, terminal, keybindings, lua, config]
sources: [raw/Key Binding - Wez's Terminal Emulator.md]
created: 2026-04-17
updated: 2026-04-17
---

## Overview

WezTerm key bindings are configured in `~/.wezterm.lua` via `config.keys`. You can override defaults, disable them, or add entirely new assignments.

## Modifier Keys

| Label | Equivalent | Platform notes |
|-------|-----------|----------------|
| `SUPER`, `CMD`, `WIN` | same key | macOS=Command, Windows=Win, Linux=Super/Hyper |
| `CTRL` | — | Left/right equivalent |
| `SHIFT` | — | Left/right equivalent |
| `ALT`, `OPT`, `META` | same key | macOS=Option, others=Alt/Meta |
| `LEADER` | modal state | WezTerm-managed, see [Leader Key](#leader-key) |
| `VoidSymbol` | remapped key | X11 only — e.g. CapsLock remapped via `setxkbmap` |

Combine modifiers with `|`: `"CMD|CTRL"`, `"LEADER|SHIFT"`.

## Key Value Types

- **Literal character** — `key = 'a'` (single unicode character)
- **Named keycode** — `key = 'F1'`, `key = 'Enter'`, `key = 'LeftArrow'`, etc.
- **`phys:` prefix** — physical position on ANSI US keyboard: `key = "phys:A"`
- **`mapped:` prefix** — post-layout OS value: `key = "mapped:a"`
- **`raw:` prefix** — OS/hardware keycode integer: `key = "raw:123"`

Default (no prefix) behavior is controlled by `key_map_preference`:
- `"Mapped"` (default since 20220408) — assumes `mapped:`
- `"Physical"` — assumes `phys:`

> **Upgrade note:** If you had `{key="N", mods="CMD"}` before v20220319, change to `{key="N", mods="CMD|SHIFT"}` or `{key="mapped:N", mods="CMD"}`.

## Basic Config Example

```lua
config.keys = {
  -- Disable a default binding
  {
    key = 'm',
    mods = 'CMD',
    action = wezterm.action.DisableDefaultAssignment,
  },
}
```

## Leader Key

A **leader** is a modal modifier — press the leader combo, then a follow-up key.

- While active, only `LEADER`-prefixed bindings fire; all other keypresses are swallowed
- Auto-cancels after `timeout_milliseconds` (default: 1000ms)

```lua
config.leader = { key = 'a', mods = 'CTRL', timeout_milliseconds = 1000 }
config.keys = {
  -- CTRL-A then | → split horizontal
  {
    key = '|',
    mods = 'LEADER|SHIFT',
    action = wezterm.action.SplitHorizontal { domain = 'CurrentPaneDomain' },
  },
  -- CTRL-A then CTRL-A → pass through CTRL-A to terminal
  {
    key = 'a',
    mods = 'LEADER|CTRL',
    action = wezterm.action.SendKey { key = 'a', mods = 'CTRL' },
  },
}
```

### CapsLock as Leader (X11)

```bash
setxkbmap -option caps:none   # remap CapsLock → VoidSymbol
```

```lua
config.leader = { key = 'VoidSymbol', mods = '', timeout_milliseconds = 1000 }
config.keys = {
  { key = '|', mods = 'LEADER|SHIFT', action = wezterm.action.SplitHorizontal { domain = 'CurrentPaneDomain' } },
  { key = '-', mods = 'LEADER',       action = wezterm.action.SplitVertical   { domain = 'CurrentPaneDomain' } },
}
```

## Discovering Raw Key Codes

Set in config to log key events:

```lua
config.debug_key_events = true
```

Then press the key to find its `raw:NNN` value.

## Key Takeaways

- `config.keys` is a list of `{key, mods, action}` tables — override or extend defaults
- Modifiers `SUPER`/`CMD`/`WIN` and `ALT`/`OPT`/`META` are platform aliases
- Use `phys:` for layout-independent bindings, `mapped:` for post-layout, `raw:` for hardware codes
- `LEADER` enables vim-style two-key combos; anything not matched is swallowed during leader mode
- `key_map_preference = "Mapped"` is the modern default (since v20220408)
- Use `DisableDefaultAssignment` to cleanly remove built-in bindings

## Related

- [[wiki/dotfiles/wezterm-default-keybindings|Default Key Assignments Table]]
- [[wiki/dotfiles/wezterm-config|WezTerm Config Structure]]
- [[wiki/dotfiles/wezterm-cli-reference|WezTerm CLI Reference]]
- [[wiki/dotfiles/terminal-cheatsheet|Terminal Cheatsheet]]

## Sources

- [WezTerm Key Binding Docs](https://wezterm.org/config/keys.html)
- Raw article: `raw/Key Binding - Wez's Terminal Emulator.md`
