obsidian/wiki/dotfiles/wezterm-key-bindings.md

title	aliases	tags	sources	created	updated
WezTerm Key Bindings	wezterm-keys wezterm-keybindings-config wezterm-leader-key	wezterm terminal keybindings lua config	raw/Key Binding - Wez's Terminal Emulator.md	2026-04-17	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
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

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)

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)

setxkbmap -option caps:none   # remap CapsLock → VoidSymbol

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:

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
• wiki/dotfiles/wezterm-config
• wiki/dotfiles/wezterm-cli-reference
• wiki/dotfiles/terminal-cheatsheet

Sources

• WezTerm Key Binding Docs
• Raw article: raw/Key Binding - Wez's Terminal Emulator.md