Skip to main content

​
Overview

Panes allow you to divide a single tab into multiple terminal sessions. WezTerm provides comprehensive pane management through key assignments for splitting, navigating, resizing, and organizing panes.

​
Creating Panes

​
SplitHorizontal

Split the current pane horizontally (side by side): 
local wezterm = require 'wezterm'
local act = wezterm.action
local config = {}

config.keys = {
  {
    key = '%',
    mods = 'CTRL|SHIFT',
    action = act.SplitHorizontal { domain = 'CurrentPaneDomain' },
  },
}

return config
​
domain
SpawnTabDomain
Domain to use for the new pane
​
args
string[]
Command to run in the new pane
​
cwd
string
Working directory for the new pane

​
SplitVertical

Split the current pane vertically (top and bottom): 
config.keys = {
  {
    key = '"',
    mods = 'CTRL|SHIFT',
    action = act.SplitVertical { domain = 'CurrentPaneDomain' },
  },
}

​
SplitPane

Advanced pane splitting with more control: 
config.keys = {
  {
    key = 'd',
    mods = 'CTRL|SHIFT',
    action = act.SplitPane {
      direction = 'Right',
      size = { Percent = 30 },
      command = { args = { 'htop' } },
    },
  },
}
​
direction
PaneDirection
required
Direction to split: 'Left', 'Right', 'Up', or 'Down'
​
size
SplitSize
Size of the new pane:
  • { Percent = 50 } - Percentage of available space (default: 50)
  • { Cells = 20 } - Fixed number of cells (characters)
​
command
SpawnCommand
Command to run in the new pane
​
top_level
boolean
default:"false"
When true, split the entire tab instead of just the current pane

​
ActivatePaneDirection

Move focus to an adjacent pane: 
config.keys = {
  {
    key = 'LeftArrow',
    mods = 'ALT',
    action = act.ActivatePaneDirection 'Left',
  },
  {
    key = 'RightArrow',
    mods = 'ALT',
    action = act.ActivatePaneDirection 'Right',
  },
  {
    key = 'UpArrow',
    mods = 'ALT',
    action = act.ActivatePaneDirection 'Up',
  },
  {
    key = 'DownArrow',
    mods = 'ALT',
    action = act.ActivatePaneDirection 'Down',
  },
}
​
direction
string
required
Direction to move focus:
  • 'Left', 'Right', 'Up', 'Down' - Navigate by direction
  • 'Next' - Move to next pane in tree order
  • 'Prev' - Move to previous pane in tree order
When multiple panes are adjacent in the specified direction, WezTerm selects the most recently activated one

​
ActivatePaneByIndex

Activate a specific pane by its index: 
config.keys = {
  {
    key = '1',
    mods = 'ALT',
    action = act.ActivatePaneByIndex(0),
  },
}
​
index
integer
required
Zero-based index of the pane to activate

​
PaneSelect

Display an interactive pane selector: 
config.keys = {
  {
    key = 'p',
    mods = 'CTRL|SHIFT',
    action = act.PaneSelect,
  },
  {
    key = 's',
    mods = 'CTRL|SHIFT',
    action = act.PaneSelect {
      mode = 'SwapWithActive',
      alphabet = 'asdfghjkl;',
    },
  },
}
​
alphabet
string
Custom alphabet for pane labels. Defaults to quick_select_alphabet config
​
mode
PaneSelectMode
What to do with the selected pane:
  • 'Activate' - Switch focus to the pane (default)
  • 'SwapWithActive' - Swap positions with active pane
  • 'SwapWithActiveKeepFocus' - Swap positions but keep focus on current pane
  • 'MoveToNewTab' - Move pane to a new tab
  • 'MoveToNewWindow' - Move pane to a new window
​
show_pane_ids
boolean
default:"false"
Show pane IDs in the selector

​
Resizing Panes

​
AdjustPaneSize

Resize the active pane: 
config.keys = {
  {
    key = 'LeftArrow',
    mods = 'CTRL|SHIFT|ALT',
    action = act.AdjustPaneSize { 'Left', 5 },
  },
  {
    key = 'RightArrow',
    mods = 'CTRL|SHIFT|ALT',
    action = act.AdjustPaneSize { 'Right', 5 },
  },
  {
    key = 'UpArrow',
    mods = 'CTRL|SHIFT|ALT',
    action = act.AdjustPaneSize { 'Up', 5 },
  },
  {
    key = 'DownArrow',
    mods = 'CTRL|SHIFT|ALT',
    action = act.AdjustPaneSize { 'Down', 5 },
  },
}
This is commonly used with key tables to create a modal resize mode

​
Resize Mode with Key Tables

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

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

config.key_tables = {
  resize_pane = {
    { key = 'LeftArrow', action = act.AdjustPaneSize { 'Left', 1 } },
    { key = 'h', action = act.AdjustPaneSize { 'Left', 1 } },
    
    { key = 'RightArrow', action = act.AdjustPaneSize { 'Right', 1 } },
    { key = 'l', action = act.AdjustPaneSize { 'Right', 1 } },
    
    { key = 'UpArrow', action = act.AdjustPaneSize { 'Up', 1 } },
    { key = 'k', action = act.AdjustPaneSize { 'Up', 1 } },
    
    { key = 'DownArrow', action = act.AdjustPaneSize { 'Down', 1 } },
    { key = 'j', action = act.AdjustPaneSize { 'Down', 1 } },
    
    -- Cancel resize mode
    { key = 'Escape', action = 'PopKeyTable' },
  },
}

​
Managing Panes

​
CloseCurrentPane

Close the currently active pane: 
config.keys = {
  {
    key = 'w',
    mods = 'CTRL',
    action = act.CloseCurrentPane { confirm = true },
  },
}
​
confirm
boolean
default:"false"
When true, shows a confirmation overlay before closing

​
TogglePaneZoomState

Zoom (maximize) the current pane, hiding others temporarily: 
config.keys = {
  {
    key = 'z',
    mods = 'CTRL|SHIFT',
    action = act.TogglePaneZoomState,
  },
}
Press the same key binding again to unzoom and restore the pane layout

​
SetPaneZoomState

Explicitly set the zoom state: 
config.keys = {
  { key = 'z', mods = 'ALT', action = act.SetPaneZoomState(true) },
  { key = 'u', mods = 'ALT', action = act.SetPaneZoomState(false) },
}
​
zoomed
boolean
required
true to zoom the pane, false to unzoom

​
RotatePanes

Rotate pane positions: 
config.keys = {
  {
    key = 'r',
    mods = 'CTRL|SHIFT',
    action = act.RotatePanes 'Clockwise',
  },
  {
    key = 'r',
    mods = 'CTRL|SHIFT|ALT',
    action = act.RotatePanes 'CounterClockwise',
  },
}
​
direction
string
required
  • 'Clockwise' - Rotate panes clockwise
  • 'CounterClockwise' - Rotate panes counter-clockwise

​
Complete Example

local wezterm = require 'wezterm'
local act = wezterm.action
local config = {}

config.keys = {
  -- Split panes
  { key = '%', mods = 'CTRL|SHIFT', action = act.SplitHorizontal { domain = 'CurrentPaneDomain' } },
  { key = '"', mods = 'CTRL|SHIFT', action = act.SplitVertical { domain = 'CurrentPaneDomain' } },
  
  -- Navigate panes
  { key = 'LeftArrow', mods = 'ALT', action = act.ActivatePaneDirection 'Left' },
  { key = 'RightArrow', mods = 'ALT', action = act.ActivatePaneDirection 'Right' },
  { key = 'UpArrow', mods = 'ALT', action = act.ActivatePaneDirection 'Up' },
  { key = 'DownArrow', mods = 'ALT', action = act.ActivatePaneDirection 'Down' },
  
  -- Close pane
  { key = 'w', mods = 'CTRL', action = act.CloseCurrentPane { confirm = true } },
  
  -- Zoom pane
  { key = 'z', mods = 'CTRL|SHIFT', action = act.TogglePaneZoomState },
}

return config