Key Bindings

Configure custom key bindings and understand default tmux shortcuts

Key bindings in tmux allow you to execute commands with keyboard shortcuts. Bindings can be customized to fit your workflow and are organized into key tables.

Key Binding Commands

bind-key

Create or modify key bindings:

bind [-nr] [-T key-table] [-N note] key command [arguments]

Flags:

• -n: Bind without requiring the prefix key (root table)
• -r: Allow key to repeat without pressing prefix again
• -T: Specify the key table (default: prefix)
• -N: Add a descriptive note for the binding

Examples:

# Bind prefix + r to reload config
bind r source-file ~/.tmux.conf \; display "Config reloaded"

# Bind without prefix
bind -n C-Left previous-window

# Repeatable binding
bind -r C-Up resize-pane -U

# With descriptive note
bind -N "Reload configuration" r source-file ~/.tmux.conf

The bind-key command is implemented in cmd-bind-key.c:54-107 and uses the key_bindings_add() function to register bindings.

unbind-key

Remove key bindings:

unbind [-n] [-T key-table] key

Example:

# Remove default C-b binding
unbind C-b

# Remove from root table
unbind -n MouseDrag1Pane

list-keys

List all key bindings:

list-keys [-1] [-N] [-T key-table] [key]

Flags:

• -1: Show only one binding
• -N: Show notes/descriptions
• -T: Filter by key table

Key Tables

Key bindings are organized into tables. From key-bindings.c:104-123, tmux uses a red-black tree structure to manage key tables efficiently.

Built-in Key Tables

Table	Purpose
prefix	Default key table, accessed after prefix key
root	Keys that work without prefix (with -n flag)
copy-mode	Keys active in copy mode (emacs style)
copy-mode-vi	Keys active in copy mode (vi style)

Using Key Tables

# Bind in prefix table (default)
bind x kill-pane

# Bind in root table
bind -n C-Left select-pane -L

# Bind in copy mode table
bind -Tcopy-mode C-c send -X cancel

Default Key Bindings

tmux initializes default bindings in key_bindings_init() (key-bindings.c:347-669). Here are the most important defaults:

Session Management

# Key bindings from key-bindings.c:352-409
bind C-z { suspend-client }            # Suspend client
bind d { detach-client }                # Detach client  
bind L { switch-client -l }             # Last client
bind s { choose-tree -Zs }             # Choose session
bind $ { command-prompt -I'#S' { rename-session -- '%%' } }

Window Management

# Key bindings from key-bindings.c:369-403
bind c { new-window }                   # Create window
bind n { next-window }                  # Next window
bind p { previous-window }              # Previous window
bind l { last-window }                  # Last window
bind w { choose-tree -Zw }             # Choose window
bind & { confirm-before -p"kill-window #W? (y/n)" kill-window }
bind , { command-prompt -I'#W' { rename-window -- '%%' } }
bind . { command-prompt -T target { move-window -t '%%' } }

# Select windows by number
bind 0 { select-window -t:=0 }
bind 1 { select-window -t:=1 }
# ... bindings for 2-9

Pane Management

# Key bindings from key-bindings.c:356-413
bind '"' { split-window }               # Split vertically
bind % { split-window -h }              # Split horizontally
bind o { select-pane -t:.+ }           # Next pane
bind x { confirm-before -p"kill-pane #P? (y/n)" kill-pane }
bind z { resize-pane -Z }              # Zoom pane
bind ! { break-pane }                  # Break to new window

# Pane navigation
bind -r Up { select-pane -U }
bind -r Down { select-pane -D }
bind -r Left { select-pane -L }
bind -r Right { select-pane -R }

# Pane resizing (repeatable)
bind -r C-Up { resize-pane -U }
bind -r C-Down { resize-pane -D }
bind -r C-Left { resize-pane -L }
bind -r C-Right { resize-pane -R }

# By 5 cells
bind -r M-Up { resize-pane -U 5 }
bind -r M-Down { resize-pane -D 5 }
bind -r M-Left { resize-pane -L 5 }
bind -r M-Right { resize-pane -R 5 }

# Swap panes
bind '{' { swap-pane -U }
bind '}' { swap-pane -D }

Layout Management

# Key bindings from key-bindings.c:414-420
bind Space { next-layout }              # Cycle layouts
bind M-1 { select-layout even-horizontal }
bind M-2 { select-layout even-vertical }
bind M-3 { select-layout main-horizontal }
bind M-4 { select-layout main-vertical }
bind M-5 { select-layout tiled }

Copy Mode

# Key bindings from key-bindings.c:387-409
bind [ { copy-mode }                    # Enter copy mode
bind PPage { copy-mode -u }            # Enter and scroll up
bind ] { paste-buffer -p }             # Paste buffer
bind = { choose-buffer -Z }            # Choose buffer
bind '#' { list-buffers }              # List buffers
bind - { delete-buffer }               # Delete most recent buffer

Copy Mode Keys (Emacs)

# Key bindings from key-bindings.c:491-565
bind -Tcopy-mode C-Space { send -X begin-selection }
bind -Tcopy-mode C-w { send -X copy-pipe-and-cancel }
bind -Tcopy-mode M-w { send -X copy-pipe-and-cancel }
bind -Tcopy-mode C-n { send -X cursor-down }
bind -Tcopy-mode C-p { send -X cursor-up }
bind -Tcopy-mode C-v { send -X page-down }
bind -Tcopy-mode M-v { send -X page-up }

Copy Mode Keys (Vi)

# Key bindings from key-bindings.c:567-654
bind -Tcopy-mode-vi v { send -X rectangle-toggle }
bind -Tcopy-mode-vi Space { send -X begin-selection }
bind -Tcopy-mode-vi Enter { send -X copy-pipe-and-cancel }
bind -Tcopy-mode-vi h { send -X cursor-left }
bind -Tcopy-mode-vi j { send -X cursor-down }
bind -Tcopy-mode-vi k { send -X cursor-up }
bind -Tcopy-mode-vi l { send -X cursor-right }

Mouse Bindings

tmux includes comprehensive mouse support (key-bindings.c:442-489):

# Mouse button 1 on pane
bind -n MouseDown1Pane { select-pane -t=; send -M }

# Mouse drag in pane
bind -n MouseDrag1Pane { 
  if -F '#{||:#{pane_in_mode},#{mouse_any_flag}}' 
    { send -M } 
    { copy-mode -M } 
}

# Mouse wheel
bind -n WheelUpPane { 
  if -F '#{||:#{alternate_on},#{pane_in_mode},#{mouse_any_flag}}' 
    { send -M } 
    { copy-mode -e } 
}

# Mouse button 2 (middle click) - paste
bind -n MouseDown2Pane { 
  select-pane -t=; 
  if -F '#{||:#{pane_in_mode},#{mouse_any_flag}}' 
    { send -M } 
    { paste -p } 
}

# Double click - select word
bind -n DoubleClick1Pane {
  select-pane -t=;
  if -F '#{||:#{pane_in_mode},#{mouse_any_flag}}'
    { send -M }
    { copy-mode -H; send -X select-word; run -d0.3; send -X copy-pipe-and-cancel }
}

# Triple click - select line
bind -n TripleClick1Pane {
  select-pane -t=;
  if -F '#{||:#{pane_in_mode},#{mouse_any_flag}}'
    { send -M }
    { copy-mode -H; send -X select-line; run -d0.3; send -X copy-pipe-and-cancel }
}

Custom Binding Examples

Here are practical custom bindings from example_tmux.conf:

Function Key Bindings

# Select higher numbered windows with function keys
bind F1 selectw -t:10
bind F2 selectw -t:11
bind F3 selectw -t:12
# ... F4 through F12 for windows 13-21

Toggle Bindings

# Toggle window size between smallest and largest
bind F set -w window-size

# Toggle monitoring activity
bind m set monitor-activity

# Toggle synchronize-panes with status message
bind y set synchronize-panes\; display 'synchronize-panes #{?synchronize-panes,on,off}'

Prefix Key Customization

# Change prefix from C-b to C-a
set -g prefix C-a
unbind C-b
bind C-a send-prefix

Key Codes

Keys can be specified in several formats:

Format	Example	Description
Character	x	Single character
Control	C-x	Control + character
Meta/Alt	M-x	Meta/Alt + character
Shift	S-Up	Shift + key
Function	F1-F12	Function keys
Special	Space, Enter, Escape	Special keys
Mouse	MouseDown1Pane	Mouse events

Repeatable Bindings

The -r flag creates repeatable bindings. After pressing the binding once, you can press just the key (without prefix) within the repeat-time window:

# Set repeat time to 1 second
set -g repeat-time 1000

# Repeatable pane resizing
bind -r Up resize-pane -U
bind -r Down resize-pane -D

# Now: prefix + Up, Up, Up (without prefix)

From key-bindings.c:222-223, repeatable bindings are marked with the KEY_BINDING_REPEAT flag.

Listing and Describing Keys

# List all bindings
tmux list-keys

# List bindings with descriptions
tmux list-keys -N

# List bindings in specific table
tmux list-keys -T copy-mode-vi

# Describe a specific key
tmux list-keys -1N C-b

Binding Best Practices

Avoid conflicts with shell/editor

Don’t bind keys that conflict with your shell or text editor. For example, C-s is used by shell flow control.

Use meaningful mnemonics

Choose key bindings that are easy to remember. For example, r for reload, | for vertical split.

Document your bindings

Use the -N flag to add notes to your custom bindings:

bind -N "Split pane vertically" | split-window -h

Group related bindings

Keep related bindings together in your config file for easier maintenance.

Changing key bindings doesn’t affect existing sessions until you reload the configuration or restart tmux.