Skip to main content

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us