Copy Mode

Entering copy mode, vi/emacs key bindings, selecting and copying text in tmux

Understanding Copy Mode

Copy mode allows you to navigate through a pane’s history, search for text, and copy content to paste buffers. It’s similar to a pager like less or a text editor’s visual mode.

Copy mode provides access to the scrollback history, which by default stores 2000 lines. You can adjust this with the history-limit option.

Entering Copy Mode

Basic Entry

C-b [         # Enter copy mode
C-b PageUp    # Enter copy mode and scroll up one page

From the command line:

tmux copy-mode

# Enter and scroll up one page
tmux copy-mode -u

# Enter and scroll down one page
tmux copy-mode -d

# Hide position indicator
tmux copy-mode -H

# Exit automatically when scrolling to bottom
tmux copy-mode -e

Exit Copy Mode

Press q (vi mode) or Escape (emacs mode) to exit copy mode.

Key Binding Modes

tmux supports two key binding sets for copy mode: vi and emacs. Set your preference with:

# Use vi key bindings (default if VISUAL or EDITOR contains 'vi')
set-option -w mode-keys vi

# Use emacs key bindings
set-option -w mode-keys emacs

Navigation in Copy Mode

Vi Key Bindings

Basic Movement

Key	Action
h	Move cursor left
j	Move cursor down
k	Move cursor up
l	Move cursor right
0	Move to start of line
$	Move to end of line
^	Move to first non-whitespace character

Word Movement

Key	Action
w	Move to next word
b	Move to previous word
e	Move to end of next word
W	Move to next space-separated word
B	Move to previous space-separated word
E	Move to end of next space-separated word

Scrolling

Key	Action
C-f	Page down
C-b	Page up
C-d	Half page down
C-u	Half page up
C-e	Scroll down
C-y	Scroll up

Jumping

Key	Action
g	Go to top of history
G	Go to bottom of history
:	Prompt for line number
H	Move to top of screen
M	Move to middle of screen
L	Move to bottom of screen

Emacs Key Bindings

Basic Movement

Key	Action
Left	Move cursor left
Down	Move cursor down
Up	Move cursor up
Right	Move cursor right
C-a	Move to start of line
C-e	Move to end of line
M-m	Move to first non-whitespace

Word Movement

Key	Action
M-f	Move to end of next word
M-b	Move to previous word

Scrolling

Key	Action
PageDown	Page down
PageUp	Page up
M-Down	Half page down
M-Up	Half page up
C-Down	Scroll down
C-Up	Scroll up

Jumping

Key	Action
M-<	Go to top of history
M->	Go to bottom of history
g	Prompt for line number
M-R	Move to top of screen
M-r	Move to middle of screen

Searching in Copy Mode

Vi Mode Searching

/pattern      # Search forward for pattern
?pattern      # Search backward for pattern
n             # Repeat last search forward
N             # Repeat last search backward

Emacs Mode Searching

C-s           # Incremental search forward
C-r           # Incremental search backward
n             # Repeat last search forward  
N             # Repeat last search backward

Search Commands

From the tmux command prompt or key bindings:

# Search forward
send-keys -X search-forward "error"

# Search backward
send-keys -X search-backward "warning"

# Search for plain text (not regex)
send-keys -X search-forward-text "literal text"

# Incremental search (with command-prompt -i)
command-prompt -i -p "Search:" \
  'send-keys -X search-forward-incremental "%%%"'

Advanced Searching

Searches use regular expressions by default. For literal string matching, use the -text variants.

Selecting and Copying Text

Vi Mode Selection

Emacs Mode Selection

Copy Commands

Explicit copy commands for use with send-keys -X:

# Copy selection
send-keys -X copy-selection
send-keys -X copy-selection-no-clear     # Don't clear selection
send-keys -X copy-selection-and-cancel   # Copy and exit

# Copy and pipe to command
send-keys -X copy-pipe "xclip -selection clipboard"
send-keys -X copy-pipe-and-cancel "pbcopy"

# Copy without selection
send-keys -X copy-line                    # Current line
send-keys -X copy-end-of-line             # From cursor to end

# Named buffers
send-keys -X copy-selection mybuffer      # Copy to named buffer

Copy Flags

# -C: Don't set terminal clipboard
# -P: Don't create paste buffer

# Copy to buffer only, not clipboard
send-keys -X copy-selection-and-cancel -C

# Copy to clipboard only, not buffer
send-keys -X copy-selection-and-cancel -P

Selection Modes

Copy mode supports different selection modes:

Character Selection (Default)

Select character by character.

# Vi mode: Space to begin
# Emacs mode: C-Space to begin

Line Selection

Select entire lines at a time.

# Vi mode: V
send-keys -X select-line

Rectangle Selection

Select a rectangular block of text.

# Vi mode: v to toggle
# Emacs mode: R to toggle

send-keys -X rectangle-on
send-keys -X rectangle-off
send-keys -X rectangle-toggle

Word Selection

Select word under cursor.

send-keys -X select-word

Jumping in Copy Mode

Quickly move within a line:

Vi Mode Jumps

f<char>       # Jump forward to next occurrence of <char>
F<char>       # Jump backward to previous occurrence of <char>
t<char>       # Jump forward to before next <char>
T<char>       # Jump backward to after previous <char>
;             # Repeat last jump
,             # Repeat last jump in reverse direction

Example:

fa            # Jump to next 'a'
;             # Jump to next 'a' again
,             # Jump back to previous 'a'

Jump Commands

send-keys -X jump-forward "x"
send-keys -X jump-backward "x"
send-keys -X jump-to-forward "x"
send-keys -X jump-to-backward "x"
send-keys -X jump-again
send-keys -X jump-reverse

Marks and Position

Setting Marks

# Vi mode: X
# Emacs mode: X
send-keys -X set-mark

# Jump to mark
M-x           # Both vi and emacs
send-keys -X jump-to-mark

Position Indicator

The position indicator shows:

• Current cursor position
• Total lines in history
• Search match count (when searching)

# Toggle position indicator visibility
P             # Both vi and emacs mode
send-keys -X toggle-position

Advanced Copy Mode Features

Scrolling Modes

# Scroll to make current line top/middle/bottom
z             # Vi mode: middle
send-keys -X scroll-middle
send-keys -X scroll-top
send-keys -X scroll-bottom

History Navigation

# Move between shell prompts (requires shell support)
send-keys -X next-prompt
send-keys -X previous-prompt

# Move to command output start
send-keys -X next-prompt -o

Prompt navigation requires your shell to emit OSC 133 escape sequences. Supported by some shells with proper configuration.

Matching Brackets

# Vi mode: %
# Emacs mode: M-C-f (forward), M-C-b (backward)
send-keys -X next-matching-bracket
send-keys -X previous-matching-bracket

Paragraph Navigation

# Vi mode: { and }
# Emacs mode: M-{ and M-}
send-keys -X previous-paragraph
send-keys -X next-paragraph

Paste Buffers

Copied text is stored in paste buffers.

Viewing Buffers

C-b #         # List all paste buffers
C-b =         # Choose buffer interactively

tmux list-buffers
tmux lsb

Pasting Buffers

C-b ]         # Paste most recent buffer

tmux paste-buffer
tmux paste-buffer -b buffer0  # Paste specific buffer

# With separator
tmux paste-buffer -s ','      # Use comma as separator
tmux paste-buffer -r          # No replacement (keep LF)

# With bracketed paste
tmux paste-buffer -p

Managing Buffers

# Delete buffer
tmux delete-buffer -b buffer0

# Save buffer to file
tmux save-buffer ~/output.txt
tmux save-buffer -b buffer2 ~/backup.txt

# Load file into buffer
tmux load-buffer ~/input.txt
tmux load-buffer -b mybuffer ~/data.txt

# Set buffer from string
tmux set-buffer "some text"
tmux set-buffer -b mybuffer "more text"

# Append to buffer
tmux set-buffer -a "appended text"

Mouse Support in Copy Mode

When mouse mode is enabled:

# Enable mouse
set-option -g mouse on

Mouse actions in copy mode:

• Click and drag - Select text
• Double-click - Select word
• Triple-click - Select line
• MouseDrag1 - Begin selection
• MouseDragEnd1 - Copy selection and exit
• WheelUp/Down - Scroll history

Mouse Copy Configuration

# Copy on mouse drag end
bind-key -T copy-mode-vi MouseDragEnd1Pane \
  send-keys -X copy-pipe-and-cancel "xclip -selection clipboard"

bind-key -T copy-mode-emacs MouseDragEnd1Pane \
  send-keys -X copy-pipe-and-cancel "pbcopy"

# Don't exit on mouse drag end
bind-key -T copy-mode-vi MouseDragEnd1Pane \
  send-keys -X copy-pipe "xclip -selection clipboard"

Customizing Copy Mode

Custom Key Bindings

# Vi mode key bindings
bind-key -T copy-mode-vi 'v' send-keys -X begin-selection
bind-key -T copy-mode-vi 'y' send-keys -X copy-selection-and-cancel
bind-key -T copy-mode-vi 'r' send-keys -X rectangle-toggle

# Emacs mode key bindings  
bind-key -T copy-mode 'v' send-keys -X begin-selection
bind-key -T copy-mode 'y' send-keys -X copy-selection-and-cancel

Copy to System Clipboard

Linux (X11)

# Vi mode
bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel \
  'xclip -in -selection clipboard'

# Emacs mode
bind-key -T copy-mode M-w send-keys -X copy-pipe-and-cancel \
  'xclip -in -selection clipboard'

macOS

# Vi mode
bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel \
  'pbcopy'

# Emacs mode
bind-key -T copy-mode M-w send-keys -X copy-pipe-and-cancel \
  'pbcopy'

Wayland

# Vi mode
bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel \
  'wl-copy'

# Emacs mode
bind-key -T copy-mode M-w send-keys -X copy-pipe-and-cancel \
  'wl-copy'

Word Separators

Customize what characters are considered word boundaries:

# Default separators
set-option -g word-separators " -_@"

# Only spaces
set-option -g word-separators " "

# No separators (treat everything as words)
set-option -g word-separators ""

Copy Mode Commands Reference

All Copy Mode Commands

Complete list of commands for send-keys -X:

Movement Commands

cursor-down
cursor-left
cursor-right
cursor-up
cursor-centre-vertical
cursor-centre-horizontal
start-of-line
end-of-line
back-to-indentation
next-word
next-word-end
next-space
next-space-end
previous-word
previous-space
top-line
middle-line
bottom-line
history-top
history-bottom

Scrolling Commands

halfpage-down
halfpage-up
page-down
page-up
scroll-down
scroll-up
scroll-middle
scroll-top
scroll-bottom

Search Commands

search-forward <text>
search-backward <text>
search-forward-text <text>
search-backward-text <text>
search-forward-incremental <text>
search-backward-incremental <text>
search-again
search-reverse

Selection Commands

begin-selection
clear-selection
stop-selection
select-line
select-word
rectangle-on
rectangle-off
rectangle-toggle
other-end

Copy Commands

copy-selection
copy-selection-and-cancel
copy-selection-no-clear
append-selection
append-selection-and-cancel
copy-line
copy-line-and-cancel
copy-end-of-line
copy-end-of-line-and-cancel
copy-pipe <command>
copy-pipe-and-cancel <command>
copy-pipe-no-clear <command>

Other Commands

cancel
goto-line <line>
jump-forward <char>
jump-backward <char>
jump-to-forward <char>
jump-to-backward <char>
jump-again
jump-reverse
jump-to-mark
set-mark
next-matching-bracket
previous-matching-bracket
next-paragraph
previous-paragraph
next-prompt
previous-prompt
refresh-from-pane
toggle-position

Practical Examples

Quick Clipboard Integration

# Enter copy mode, select text, copy to clipboard
set-option -g mouse on
set-option -w mode-keys vi

bind-key -T copy-mode-vi v send-keys -X begin-selection
bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel 'xclip -selection clipboard'
bind-key -T copy-mode-vi MouseDragEnd1Pane send-keys -X copy-pipe-and-cancel 'xclip -selection clipboard'

# Paste from clipboard
bind-key C-v run "xclip -selection clipboard -o | tmux load-buffer - ; tmux paste-buffer"

Search and Copy Workflow

# 1. Enter copy mode
C-b [

# 2. Search for text
/error

# 3. Navigate to desired match
n     # Next match
N     # Previous match

# 4. Begin selection
Space

# 5. Extend selection
l l l  # Move right

# 6. Copy
Enter

# 7. Paste elsewhere
C-b ]

Copy Command Output

# Run command and copy output
bind-key C-c run-shell \
  'tmux capture-pane -p | tail -n 20 | xclip -selection clipboard'

# Copy entire pane history
bind-key C-h run-shell \
  'tmux capture-pane -pS -32768 | xclip -selection clipboard'

Incremental Search Setup

# Vi mode incremental search
bind-key -T copy-mode-vi / command-prompt -i -p "Search:" \
  'send-keys -X search-forward-incremental "%%%"'
  
bind-key -T copy-mode-vi ? command-prompt -i -p "Search:" \
  'send-keys -X search-backward-incremental "%%%"'