Binding Keys in tmux

To list all current key bindings, including any custom bindings you’ve added and bindings added by plugins:

  • Ctrl + b ?
  • tmux list-keys or tmux lsk in a shell inside tmux
  • list-keys or lsk at tmux’s command prompt (Ctrl + b :)

The bind-key and unbind-key commands (aliases bind and unbind) change key bindings in tmux. Like all tmux commands a bind or unbind command can be entered in three different ways:

  1. By running tmux bind ... in a shell inside tmux
  2. By hitting Ctrl + b : in tmux and then entering bind ... into tmux’s command prompt
  3. By adding a bind ... line to your ~/.tmux.conf file to bind the key at startup

For example:

bind C-t new-window

Now Ctrl + b Ctrl + t will open a new window.

To remove the key binding:

unbind C-t

The C- stands for Control. There’s also S- for Shift and M- for Alt, e.g. bind M-t new-window, bind -n M-S-Left swap-window -t +1. There are several special key names for use in bind commands, including: Up, Down, Left, Right, BSpace, Delete, End, Enter, Escape, F1 … F12, Home, Insert, PageDown or PgDn, PageUp or PgUp, Space and Tab.

S- doesn’t work with keys that send a different character when Shift‘ed. bind S-n ..., bind S-1 ..., etc don’t work. Use bind N ..., bind ! ..., etc instead.

But if you want to bind Alt + Shift + ←, for example, then it is bind M-S-Left ....

Shift‘d keys also don’t work with Ctrl because Ctrl-modified keys are case-insensitive in terminals. So while you can do bind C-N ... the binding will be triggered by either Ctrl + Shift + n or just Ctrl + n.

There are various other modifier key limitations as well, see Modifier Keys on the tmux wiki.

Every keybinding lives in a key table. There are three built-in key tables:

  1. prefix: Keys in this table must be pressed after the prefix Ctrl + b to trigger the binding. This is the table that the bind command uses by default. Example: bind C-t new-window

  2. root: Keys in this table can just be pressed, without any prefix. Use -n (a shortcut for -T root) to bind keys in this table. Example: bind -n C-t new-window

  3. copy-mode or copy-mode-vi for when in copy mode, depending on whether you’re using emacs- or vi-style key bindings mode (add set-window-option -g mode-keys vi to your ~/.tmux.conf file to force vi-style). Use -T copy-mode-vi to bind keys in this table. Example: bind -T copy-mode-vi C-t new-window

Repeatable prefix key bindings

For key bindings in the prefix table the -r option can be used to make them repeatable. For example with tmux bind -r t new-window Ctrl + b t is needed to open a first new window, then you can keep hitting t to open more without having to hit Ctrl + b each time. The repeat-time setting decides how much time you have to repeat the key before the prefix times out (default: 500 milliseconds).

Binding a key to run multiple commands at once

You can use \; to separate multiple commands in a single key binding:

bind t new-window \; display-message "new window opened"

If using the tmux bind shell command you may need to quote the commands instead:

tmux bind t 'new-window; display-message "new window opened"'

A multiline format is also possible by ending each line with \ or (if the line is part of the command) \; \. Example:

bind -n DoubleClick1Pane \
    select-pane \; \
    copy-mode -M \; \
    send-keys -X select-word \; \
    send-keys -X copy-pipe-no-clear "xsel -i"

Binding a sequence of keys: custom key tables

You can bind keys in custom named key tables and use the switch-client command to move between key tables. This enables sequences of keys to be bound. For example to make abc in quick succession open a new window:

bind -T root       a switch-client -T my_table_1
bind -T my_table_1 b switch-client -T my_table_2
bind -T my_table_2 c new-window

Binding " and '

To bind " or ' you need to put them in quotes:

bind '"' split-window
bind "'" new-window

Binding mouse events

If tmux’s mouse support is enabled (set -g mouse on) then bind can also bind mouse events. For example to make clicking the Left Mouse Button on a pane open a new window:

bind -n MouseDown1Pane new-window

The mouse events are MouseDown1, MouseUp1, MouseDrag1, MouseDragEnd1, DoubleClick1, TripleClick1, MouseDown2, MouseUp2, MouseDrag2, MouseDragEnd2, DoubleClick2, TripleClick2, MouseDown3, MouseUp3, MouseDrag3, MouseDragEnd3, DoubleClick3, TripleClick3, WheelUp, WheelDown. Each event always needs to be suffixed with one of the target locations Pane, Border, Status (the window list in the status line), StatusLeft, StatusRight or StatusDefault (any other part of the status line that isn’t the window list or left or right parts).

Mouse button 2 (MouseDown2, MouseUp2, …) is the middle mouse button and 3 (MouseDown3, MouseUp3, …) is the right button.

The special token {mouse} or = in a mouse event bind command resolves to the target-window or target-pane that was clicked on, for when you need the target window or pane in the bound command. For example bind -n MouseDown1Pane select-pane -t {mouse} makes clicking on a pane select that pane. bind -n MouseDown1Status select-window -t = makes clicking on a window in the status line select that window.