Key Bindings

Configure keyboard shortcuts and key assignments in WezTerm

Overview

WezTerm allows you to customize keyboard shortcuts through the keys configuration option in your .wezterm.lua file. You can override default assignments, add new bindings, or disable existing ones.

Basic Key Binding Configuration

Key bindings are defined in the config.keys table:

local wezterm = require 'wezterm'
local config = wezterm.config_builder()

config.keys = {
  {
    key = 't',
    mods = 'CTRL',
    action = wezterm.action.SpawnTab 'CurrentPaneDomain',
  },
  {
    key = 'w',
    mods = 'CTRL',
    action = wezterm.action.CloseCurrentTab { confirm = true },
  },
}

return config

Modifier Keys

The following modifier keys are supported:

SUPER | CMD | WIN · modifier

On macOS: Command key. On Windows: Windows key. On Linux: Super or Hyper key.

CTRL · modifier

The Control key. Left and right are equivalent.

SHIFT · modifier

The Shift key. Left and right are equivalent.

ALT | OPT | META · modifier

On macOS: Option key. On other systems: Alt or Meta key.

LEADER · modifier

A special modal modifier state. See Leader Key below.

You can combine modifiers using the | symbol:

config.keys = {
  { key = 'n', mods = 'CTRL|SHIFT', action = wezterm.action.SpawnWindow },
}

Key Codes

The key value can be:

• A single character: 'a', '1', '=', etc.
• Special keys: Enter, Tab, Backspace, Delete, Escape, PageUp, PageDown, Home, End
• Arrow keys: LeftArrow, RightArrow, UpArrow, DownArrow
• Function keys: F1 through F24
• Numpad keys: Numpad0 through Numpad9, Multiply, Add, Subtract, Divide
• Media keys: VolumeUp, VolumeDown, VolumeMute, MediaPlayPause, MediaNextTrack, MediaPrevTrack

Physical vs Mapped Keys

WezTerm supports two ways to reference keys:

Physical Keys

Physical keys reference the physical position on an ANSI US keyboard:

config.keys = {
  { key = 'phys:A', mods = 'CTRL', action = wezterm.action.ActivateTab(0) },
}

Mapped Keys

Mapped keys reference the character produced after keyboard layout mapping:

config.keys = {
  { key = 'mapped:a', mods = 'CTRL', action = wezterm.action.ActivateTab(0) },
}

Key Map Preference

Control the default behavior with key_map_preference:

config.key_map_preference = 'Physical' -- or 'Mapped'

Disabling Default Bindings

You can disable default key bindings:

config.keys = {
  -- Turn off CMD-m Hide action on macOS
  {
    key = 'm',
    mods = 'CMD',
    action = wezterm.action.DisableDefaultAssignment,
  },
}

Leader Key

The leader key enables tmux-style key bindings with a prefix:

config.leader = { key = 'a', mods = 'CTRL', timeout_milliseconds = 1000 }

config.keys = {
  -- Leader + c creates a new tab
  {
    key = 'c',
    mods = 'LEADER',
    action = wezterm.action.SpawnTab 'CurrentPaneDomain',
  },
  -- Leader + | splits horizontally
  {
    key = '|',
    mods = 'LEADER|SHIFT',
    action = wezterm.action.SplitHorizontal { domain = 'CurrentPaneDomain' },
  },
  -- Leader + - splits vertically
  {
    key = '-',
    mods = 'LEADER',
    action = wezterm.action.SplitVertical { domain = 'CurrentPaneDomain' },
  },
}

The leader key must be pressed within timeout_milliseconds before the next key.

Key Tables

Key tables enable modal key bindings:

config.leader = { key = 'a', mods = 'CTRL' }

config.keys = {
  {
    key = 'r',
    mods = 'LEADER',
    action = wezterm.action.ActivateKeyTable {
      name = 'resize_pane',
      one_shot = false,
    },
  },
}

config.key_tables = {
  resize_pane = {
    { key = 'LeftArrow', action = wezterm.action.AdjustPaneSize { 'Left', 1 } },
    { key = 'RightArrow', action = wezterm.action.AdjustPaneSize { 'Right', 1 } },
    { key = 'UpArrow', action = wezterm.action.AdjustPaneSize { 'Up', 1 } },
    { key = 'DownArrow', action = wezterm.action.AdjustPaneSize { 'Down', 1 } },
    { key = 'Escape', action = 'PopKeyTable' },
  },
}

Common Key Binding Examples

Tabs

config.keys = {
  { key = 't', mods = 'CTRL', action = wezterm.action.SpawnTab 'CurrentPaneDomain' },
  { key = 'w', mods = 'CTRL', action = wezterm.action.CloseCurrentTab { confirm = true } },
  { key = 'Tab', mods = 'CTRL', action = wezterm.action.ActivateTabRelative(1) },
  { key = 'Tab', mods = 'CTRL|SHIFT', action = wezterm.action.ActivateTabRelative(-1) },
}

Panes

config.keys = {
  { key = '"', mods = 'CTRL|SHIFT', action = wezterm.action.SplitVertical { domain = 'CurrentPaneDomain' } },
  { key = '%', mods = 'CTRL|SHIFT', action = wezterm.action.SplitHorizontal { domain = 'CurrentPaneDomain' } },
  { key = 'h', mods = 'CTRL|SHIFT', action = wezterm.action.ActivatePaneDirection 'Left' },
  { key = 'l', mods = 'CTRL|SHIFT', action = wezterm.action.ActivatePaneDirection 'Right' },
}

Font Size

config.keys = {
  { key = '+', mods = 'CTRL', action = wezterm.action.IncreaseFontSize },
  { key = '-', mods = 'CTRL', action = wezterm.action.DecreaseFontSize },
  { key = '0', mods = 'CTRL', action = wezterm.action.ResetFontSize },
}

See Also

• Key Assignment Actions
• Mouse Bindings
• Default Key Bindings