SOP-005: Copy Mode

Fresh

Field	Value
Document ID	SOP-005
Version	1.1
Status	Active
tmux Version	3.6b
Last Updated	2026-05-26

Purpose

Navigate scrollback history, search text, and copy/paste content within tmux.

Prerequisites

• tmux installed (SOP-001)
• Active tmux session

Copy Mode Overview

Procedure

Entering Copy Mode

Method	Action
Ctrl+b [	Enter copy mode
Ctrl+b PgUp	Enter copy mode and scroll up

Setting Vi Keys (Recommended)

Add to ~/.tmux.conf:

setw -g mode-keys vi

This enables vi-style navigation in copy mode.

Navigation (Vi Mode)

Key	Action
h j k l	Move cursor left/down/up/right
w	Forward one word
b	Back one word
0	Start of line
$	End of line
g	Go to top
G	Go to bottom
Ctrl+u	Page up
Ctrl+d	Page down

Searching

Key	Action
/	Search forward
?	Search backward
n	Next match
N	Previous match

Selecting Text

Key	Action
Space	Start selection
v	Start selection (vi mode)
V	Select line (vi mode)
Ctrl+v	Rectangle selection
Esc	Clear selection
Enter	Copy selection

Copy Workflow

1. Enter copy mode: Ctrl+b [
2. Navigate to where you want to start copying
3. Start selection: Space (or v in vi mode)
4. Navigate to end of selection
5. Copy: Enter
6. Paste: Ctrl+b ]

Pasting

Method	Action
Ctrl+b ]	Paste most recent buffer
:paste-buffer	Paste buffer
:choose-buffer	Choose buffer to paste

Buffer Management

# Show buffer contents
:show-buffer

# List all buffers
:list-buffers

# Save buffer to file
:save-buffer filename.txt

# Load file to buffer
:load-buffer filename.txt

# Delete specific buffer
:delete-buffer -b 1

# Choose buffer interactively
:choose-buffer

Capturing Pane Content

# Capture visible pane content
:capture-pane

# Capture with history
:capture-pane -S -1000    # Last 1000 lines

# Capture and save to file
:capture-pane -S - -E - -p > output.txt

Copy Mode Quick Reference

Emacs Keys (Default)

Key	Action
Ctrl+Space	Start selection
Ctrl+w	Copy selection
Alt+w	Copy selection
Ctrl+g	Clear selection
Ctrl+s	Search forward
Ctrl+r	Search backward

Vi Keys (After setw -g mode-keys vi)

Key	Action
v	Start selection
y	Copy selection (yank)
Enter	Copy selection
Esc	Clear selection
/	Search forward
?	Search backward

Enhanced Vi Copy Mode

Add to ~/.tmux.conf for better vi-style copying:

# Vi mode
setw -g mode-keys vi

# Vi-style copy/paste
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

# Copy to system clipboard (macOS)
bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "pbcopy"

# Copy to system clipboard (Linux with xclip)
# bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "xclip -selection clipboard"

Copy Mode Enhancements New in 3.6

tmux 3.6 added several copy mode improvements:

Case Insensitive Search

Search in modes now matches the copy mode convention: an all lowercase search term searches case insensitively (emacs style). Type any uppercase letter to make the search case sensitive. No configuration needed.

Selection Mode Command

The selection-mode command sets the selection mode explicitly while in copy mode, instead of toggling through rectangle/line/character. Bind it in copy-mode-vi if you want a dedicated key:

# Example: jump straight to block (rectangle) selection
bind-key -T copy-mode-vi C-v send-keys -X selection-mode block

Centre the Cursor

New commands recenter the viewport on the cursor in copy mode, like zz in vim. Bind a key to the centre command for quick reorientation in long scrollback.

Copy Without Clipboard or Buffer

Copy commands accept two new flags:

Flag	Effect
-C	Do not send the copied text to the clipboard
-P	Do not add the copied text as a paste buffer

# Copy to a pipe only, skip clipboard and paste buffer
bind-key -T copy-mode-vi Y send-keys -X -C -P copy-pipe "wc -l"

Quieter Confirmations

The -y flag disables confirmation prompts in modes, useful for scripted or fast workflows.

Position and Selection Styling

Three new options control the look of copy mode:

set -g copy-mode-position-style 'fg=#000000,bg=#89b4fa'
set -g copy-mode-selection-style 'fg=#000000,bg=#a6e3a1'
set -g copy-mode-position-format '#{scroll_position}/#{history_size}'

Mouse wheel

In tmux 3.6 the mouse wheel no longer enters copy mode while an application is using the alternate screen (for example less or vim), so scrolling passes through to the application as expected.

Verification

Test copy/paste workflow:

# 1. Enter copy mode
Ctrl+b [

# 2. You should see [0/0] in the top-right

# 3. Navigate with arrows or vi keys

# 4. Press q to exit

# 5. Check buffers
:list-buffers

Troubleshooting

Can't scroll in copy mode

Solution

Make sure you're in copy mode (Ctrl+b [). The indicator [0/0] should appear in the corner.

Vi keys not working

Solution

Enable vi mode in your config:

# Add to ~/.tmux.conf
setw -g mode-keys vi

# Reload config
tmux source-file ~/.tmux.conf

Paste not working

Solution

Make sure you copied something first. Check buffers:

:list-buffers

If empty, nothing was copied.

Need to copy to system clipboard

Solution

Use clipboard integration:

macOS:

# In ~/.tmux.conf
bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "pbcopy"

Linux (with xclip):

bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "xclip -sel clip"

See Also

• SOP-006: Configuration
• SOP-004: Pane Management
• Quick Reference: Shortcuts