Key Binding Configuration

WezTerm provides a powerful and flexible key binding system that allows you to customize keyboard shortcuts, create modal key tables, and configure leader keys.

Basic Key Bindings

Defining Key Bindings

Key bindings are configured using the keys configuration option:

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

config.keys = {
  -- Create a new tab in the same domain
  {
    key = 't',
    mods = 'CTRL|SHIFT',
    action = act.SpawnTab 'CurrentPaneDomain',
  },
  -- Close the current tab
  {
    key = 'w',
    mods = 'CTRL|SHIFT',
    action = act.CloseCurrentTab { confirm = true },
  },
}

return config

keys

array

default:"[]"

An array of key binding definitions. Each binding specifies a key, modifiers, and an action.

Key Binding Structure

Each key binding is a table with these fields:

key

string

required

The key to bind. Can be a character (‘a’), named key (‘Enter’, ‘Tab’, ‘F1’), or keycode.

mods

string

default:"''"

Modifier keys, combined with |. Valid values: SHIFT, CTRL, ALT, SUPER, CMD, WIN, META

action

KeyAssignment

required

The action to perform when the key combination is pressed.

Modifier Keys

config.keys = {
  { key = 'c', mods = 'CTRL', action = act.CopyTo 'Clipboard' },
}

SUPER maps to CMD on macOS and WIN on Windows/Linux
CMD and WIN are aliases and can be used interchangeably
Modifiers are case-insensitive

Common Key Actions

Tab Management

config.keys = {
  -- Create new tab
  { key = 't', mods = 'CTRL|SHIFT', action = act.SpawnTab 'CurrentPaneDomain' },
  
  -- Close current tab
  { key = 'w', mods = 'CTRL|SHIFT', action = act.CloseCurrentTab { confirm = true } },
  
  -- Switch to next tab
  { key = 'Tab', mods = 'CTRL', action = act.ActivateTabRelative(1) },
  
  -- Switch to previous tab
  { key = 'Tab', mods = 'CTRL|SHIFT', action = act.ActivateTabRelative(-1) },
  
  -- Switch to specific tab
  { key = '1', mods = 'ALT', action = act.ActivateTab(0) },
  { key = '2', mods = 'ALT', action = act.ActivateTab(1) },
  { key = '3', mods = 'ALT', action = act.ActivateTab(2) },
}

Pane Management

config.keys = {
  -- Split horizontally
  {
    key = '|',
    mods = 'CTRL|SHIFT',
    action = act.SplitHorizontal { domain = 'CurrentPaneDomain' },
  },
  
  -- Split vertically
  {
    key = '_',
    mods = 'CTRL|SHIFT',
    action = act.SplitVertical { domain = 'CurrentPaneDomain' },
  },
  
  -- Close current pane
  {
    key = 'x',
    mods = 'CTRL|SHIFT',
    action = act.CloseCurrentPane { confirm = true },
  },
  
  -- Navigate panes
  { key = 'h', mods = 'CTRL|SHIFT', action = act.ActivatePaneDirection 'Left' },
  { key = 'l', mods = 'CTRL|SHIFT', action = act.ActivatePaneDirection 'Right' },
  { key = 'k', mods = 'CTRL|SHIFT', action = act.ActivatePaneDirection 'Up' },
  { key = 'j', mods = 'CTRL|SHIFT', action = act.ActivatePaneDirection 'Down' },
}

Copy and Paste

config.keys = {
  -- Copy to clipboard
  { key = 'c', mods = 'CTRL|SHIFT', action = act.CopyTo 'Clipboard' },
  
  -- Paste from clipboard
  { key = 'v', mods = 'CTRL|SHIFT', action = act.PasteFrom 'Clipboard' },
  
  -- Copy to primary selection (X11)
  { key = 'c', mods = 'CTRL', action = act.CopyTo 'PrimarySelection' },
  
  -- Paste from primary selection (X11)
  { key = 'v', mods = 'CTRL', action = act.PasteFrom 'PrimarySelection' },
}

config.keys = {
  -- Increase font size
  { key = '+', mods = 'CTRL', action = act.IncreaseFontSize },
  { key = '=', mods = 'CTRL', action = act.IncreaseFontSize },
  
  -- Decrease font size
  { key = '-', mods = 'CTRL', action = act.DecreaseFontSize },
  
  -- Reset font size
  { key = '0', mods = 'CTRL', action = act.ResetFontSize },
}

Scrollback

config.keys = {
  -- Scroll up one page
  { key = 'PageUp', mods = 'SHIFT', action = act.ScrollByPage(-1) },
  
  -- Scroll down one page
  { key = 'PageDown', mods = 'SHIFT', action = act.ScrollByPage(1) },
  
  -- Scroll to top
  { key = 'Home', mods = 'SHIFT', action = act.ScrollToTop },
  
  -- Scroll to bottom
  { key = 'End', mods = 'SHIFT', action = act.ScrollToBottom },
}

Disabling Default Key Bindings

To start with a clean slate and define only your own key bindings:

disable_default_key_bindings

boolean

default:"false"

When true, WezTerm’s default key bindings are disabled.

config.disable_default_key_bindings = true

-- Then define only the keys you want
config.keys = {
  { key = 'c', mods = 'CTRL|SHIFT', action = act.CopyTo 'Clipboard' },
  { key = 'v', mods = 'CTRL|SHIFT', action = act.PasteFrom 'Clipboard' },
}

Leader Key

A leader key works like in tmux - you press the leader key combination, then press another key within a timeout:

leader

table

default:"nil"

Configuration for the leader key. Includes the key, modifiers, and timeout.

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

config.keys = {
  -- Send CTRL-A when pressing CTRL-A twice
  {
    key = 'a',
    mods = 'LEADER|CTRL',
    action = act.SendKey { key = 'a', mods = 'CTRL' },
  },
  
  -- Split horizontal with leader + |
  {
    key = '|',
    mods = 'LEADER|SHIFT',
    action = act.SplitHorizontal { domain = 'CurrentPaneDomain' },
  },
  
  -- Split vertical with leader + -
  {
    key = '-',
    mods = 'LEADER',
    action = act.SplitVertical { domain = 'CurrentPaneDomain' },
  },
}

When a key binding uses the LEADER modifier, it requires pressing the leader key first.

Key Tables

Key tables allow you to create modal key binding sets, similar to vim modes:

key_tables

table

default:"{}"

A table mapping key table names to arrays of key bindings.

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

config.keys = {
  -- Enter resize mode
  {
    key = 'r',
    mods = 'LEADER',
    action = act.ActivateKeyTable {
      name = 'resize_pane',
      one_shot = false,
    },
  },
}

config.key_tables = {
  resize_pane = {
    { key = 'h', action = act.AdjustPaneSize { 'Left', 5 } },
    { key = 'l', action = act.AdjustPaneSize { 'Right', 5 } },
    { key = 'k', action = act.AdjustPaneSize { 'Up', 5 } },
    { key = 'j', action = act.AdjustPaneSize { 'Down', 5 } },
    
    -- Cancel the mode
    { key = 'Escape', action = 'PopKeyTable' },
    { key = 'Enter', action = 'PopKeyTable' },
  },
}

Key Table Options

When activating a key table:

name

string

required

The name of the key table to activate.

one_shot

boolean

default:"true"

When true, the key table is automatically deactivated after one key press.

timeout_milliseconds

number

default:"nil"

Optional timeout after which the key table is automatically deactivated.

replace_current

boolean

default:"false"

When true, replaces the current key table instead of stacking.

Physical vs Mapped Keys

key_map_preference

string

default:"'Mapped'"

Controls whether keys are matched by physical position or mapped character. Valid values: Physical, Mapped

config.key_map_preference = 'Physical'

You can also specify keys using explicit physical or mapped notation:

config.keys = {
  -- Match by physical key position (ANSI US layout)
  { key = 'phys:A', mods = 'CTRL', action = act.SendString 'Hello' },
  
  -- Match by mapped character
  { key = 'mapped:a', mods = 'CTRL', action = act.SendString 'World' },
  
  -- Match by raw scan code
  { key = 'raw:123', mods = 'CTRL', action = act.SendString 'Raw' },
}

Mouse Bindings

You can also bind mouse events to actions:

mouse_bindings

array

default:"[]"

An array of mouse binding definitions.

config.mouse_bindings = {
  -- Right click to paste
  {
    event = { Down = { streak = 1, button = 'Right' } },
    mods = 'NONE',
    action = act.PasteFrom 'Clipboard',
  },
  
  -- CTRL-click to open hyperlink
  {
    event = { Up = { streak = 1, button = 'Left' } },
    mods = 'CTRL',
    action = act.OpenLinkAtMouseCursor,
  },
  
  -- Middle click to paste primary selection
  {
    event = { Down = { streak = 1, button = 'Middle' } },
    mods = 'NONE',
    action = act.PasteFrom 'PrimarySelection',
  },
}

Disable Default Mouse Bindings

disable_default_mouse_bindings

boolean

default:"false"

When true, WezTerm’s default mouse bindings are disabled.

config.disable_default_mouse_bindings = true

Debug Key Events

debug_key_events

boolean

default:"false"

When true, logs all key events to help debug key binding issues.

config.debug_key_events = true

This will show detailed information about key presses in the debug overlay (CTRL+SHIFT+L).

Complete Key Configuration Example

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

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

-- Key bindings
config.keys = {
  -- Tabs
  { key = 't', mods = 'CTRL|SHIFT', action = act.SpawnTab 'CurrentPaneDomain' },
  { key = 'w', mods = 'CTRL|SHIFT', action = act.CloseCurrentTab { confirm = true } },
  { key = 'Tab', mods = 'CTRL', action = act.ActivateTabRelative(1) },
  { key = 'Tab', mods = 'CTRL|SHIFT', action = act.ActivateTabRelative(-1) },
  
  -- Panes
  {
    key = '|',
    mods = 'LEADER|SHIFT',
    action = act.SplitHorizontal { domain = 'CurrentPaneDomain' },
  },
  {
    key = '-',
    mods = 'LEADER',
    action = act.SplitVertical { domain = 'CurrentPaneDomain' },
  },
  { key = 'h', mods = 'LEADER', action = act.ActivatePaneDirection 'Left' },
  { key = 'l', mods = 'LEADER', action = act.ActivatePaneDirection 'Right' },
  { key = 'k', mods = 'LEADER', action = act.ActivatePaneDirection 'Up' },
  { key = 'j', mods = 'LEADER', action = act.ActivatePaneDirection 'Down' },
  
  -- Resize mode
  {
    key = 'r',
    mods = 'LEADER',
    action = act.ActivateKeyTable {
      name = 'resize_pane',
      one_shot = false,
    },
  },
  
  -- Copy and Paste
  { key = 'c', mods = 'CTRL|SHIFT', action = act.CopyTo 'Clipboard' },
  { key = 'v', mods = 'CTRL|SHIFT', action = act.PasteFrom 'Clipboard' },
  
  -- Font size
  { key = '+', mods = 'CTRL', action = act.IncreaseFontSize },
  { key = '-', mods = 'CTRL', action = act.DecreaseFontSize },
  { key = '0', mods = 'CTRL', action = act.ResetFontSize },
}

-- Key tables
config.key_tables = {
  resize_pane = {
    { key = 'h', action = act.AdjustPaneSize { 'Left', 5 } },
    { key = 'l', action = act.AdjustPaneSize { 'Right', 5 } },
    { key = 'k', action = act.AdjustPaneSize { 'Up', 5 } },
    { key = 'j', action = act.AdjustPaneSize { 'Down', 5 } },
    { key = 'Escape', action = 'PopKeyTable' },
  },
}

return config

Configuration

wezterm Module

Key Assignments

Events

Objects

Key Binding Configuration

Key Binding Configuration

Basic Key Bindings

Defining Key Bindings

Key Binding Structure

Modifier Keys

Common Key Actions

Tab Management

Pane Management

Copy and Paste

Font Size

Scrollback

Disabling Default Key Bindings

Leader Key

Key Tables

Key Table Options

Physical vs Mapped Keys

Mouse Bindings

Disable Default Mouse Bindings

Debug Key Events

Complete Key Configuration Example

See Also

Configuration

wezterm Module

Key Assignments

Events

Objects

​Key Binding Configuration

​Basic Key Bindings

​Defining Key Bindings

​Key Binding Structure

​Modifier Keys

​Common Key Actions

​Tab Management

​Pane Management

​Copy and Paste

​Font Size

​Scrollback

​Disabling Default Key Bindings

​Leader Key

​Key Tables

​Key Table Options

​Physical vs Mapped Keys

​Mouse Bindings

​Disable Default Mouse Bindings

​Debug Key Events

​Complete Key Configuration Example

​See Also

Key Binding Configuration

Basic Key Bindings

Defining Key Bindings

Key Binding Structure

Modifier Keys

Common Key Actions

Tab Management

Pane Management

Copy and Paste

Font Size

Scrollback

Disabling Default Key Bindings

Leader Key

Key Tables

Key Table Options

Physical vs Mapped Keys

Mouse Bindings

Disable Default Mouse Bindings

Debug Key Events

Complete Key Configuration Example

See Also