Copy Mode: Scrolling, Searching, Selecting, Yanking
What Copy Mode Is
In normal tmux, the cursor lives at the bottom of the pane and the scrollback is read-only. You can't move the cursor up, can't select text with the keyboard, can't search. Copy mode is the second mode that lets you do all of those things.
Think of it as vim for the terminal's scrollback.
Entering and Leaving
<prefix> [ enter copy mode
q leave (Esc also works in vi mode)
The pane's bottom-right shows a line/column indicator when you're in copy mode:
[1/847] line 1 of 847 in the scrollback
Everything up to the end of the buffer is available. Scroll back to what you did an hour ago, then q to return.
vi Mode vs emacs Mode
tmux supports two key schemes in copy mode. By default it uses emacs. Most vim users flip to vi mode:
setw -g mode-keys vi
This tutorial uses vi mode bindings throughout. If you stick with emacs, translate as needed (or read man tmux for the full binding list).
Moving in Copy Mode
vi-style motions work:
h j k l left, down, up, right
w b e word motions
0 ^ $ start, first-non-blank, end of line
gg G top, bottom of the buffer
Ctrl-u half page up
Ctrl-d half page down
Ctrl-b page up
Ctrl-f page down
H M L top, middle, bottom of screen
{count}G jump to line {count}
All the vim muscle memory transfers. If you came from emacs bindings, M-v, C-v, C-a, C-e, and friends work there.
Searching
/ search forward (type pattern, Enter)
? search backward
n next match
N previous match
After entering copy mode, /error searches forward for "error". n jumps to the next one. q to leave copy mode when you're done.
Incremental search is on by default, so you see matches highlight as you type.
Searching from the command line
Paste a pattern directly:
<prefix> :copy-mode -u
<prefix> :send-keys ?error Enter
Useful in scripts that want to position a pane for review.
Selecting Text
In vi mode:
Space or v start selection
V line-wise selection
Ctrl-v rectangular selection
Enter or y yank the selection
Esc or q cancel
Move the cursor to where the selection should start, press v, move the cursor to the other end, press y. The text goes into the tmux paste buffer.
Pasting
<prefix> ] paste the most recent buffer
Paste drops the contents of the buffer at the cursor position of whatever shell is currently focused. If you're in vim, it goes into insert mode (which is probably not what you want: see system clipboard, below).
The buffer stack
tmux keeps a list of buffers:
<prefix> :list-buffers list all buffers
<prefix> = interactive buffer picker
<prefix> :paste-buffer -b 2 paste a specific buffer
Copying new text pushes onto the stack. Old buffers stick around, which is handy if you made several copies before pasting.
System Clipboard Integration
Getting tmux yanks into your operating system's clipboard takes a little configuration. Two common ways:
1. set-clipboard (built-in)
Modern tmux can push selections to the terminal via OSC 52 escape sequences:
set -g set-clipboard on
Requires a terminal emulator that respects OSC 52 (iTerm2, WezTerm, Kitty, Alacritty with recent versions, and others). If your terminal doesn't support it, nothing happens; no error.
2. tmux-yank plugin
The tmux-yank plugin bridges to pbcopy (macOS), xclip or xsel (X11), or wl-copy (Wayland) under the hood:
set -g @plugin 'tmux-plugins/tmux-yank'
With it installed (chapter 10), y in copy mode yanks to the system clipboard automatically. Y yanks the whole line. In practice, tmux-yank is the more reliable path.
Mouse Support
Enable mouse:
set -g mouse on
Now:
- Scroll the wheel: scroll the pane (enters copy mode briefly)
- Drag to select: copy the selection into a buffer
- Click to focus a pane
- Drag pane borders to resize
Some people love it. Some find it defeats the point of tmux. Try it; decide.
A Realistic Copy Mode Flow
You ran a command an hour ago and want to copy its output into a bug report.
<prefix> [ enter copy mode
?Error search backward for "Error"
n next match, if needed
V select the whole line
j j j extend selection down 3 lines
y yank
q leave copy mode
Now <prefix> ] pastes into any pane, or if you have system clipboard integration set up, Cmd-V or Ctrl-V in another app works.
Copy Mode Conveniences
<prefix> PgUp enter copy mode and page up in one go
Many people bind this. It's the single most natural way to scroll: start to scroll, tmux puts you in copy mode automatically.
Rebind C-u, C-d, or any scroll key in your config:
bind -n S-PageUp copy-mode -u
Now Shift+PageUp enters copy mode and goes up a page, no prefix required.
Wrap selection
In vi mode, wrap-search is on by default: searching past the top wraps around. Turn off if you don't like it:
set -g wrap-search off
Editing in Copy Mode
Copy mode in recent tmux supports surprisingly capable bindings if you're in the mood:
w W b B e E word motions
f F t T find-char
; , repeat find
% matching bracket
* search for word under cursor
You can do most of what vim does to navigate, minus the editing. It is read-only.
Common Pitfalls
"Scrolling in the terminal doesn't scroll tmux scrollback." Depends on your terminal and mouse setting. With mouse on, scroll-wheel enters copy mode and scrolls. Without, the scroll-wheel scrolls your terminal emulator's buffer, not tmux's, which may show you unrelated text.
"I yanked in copy mode but paste in another app gave me nothing." The tmux paste buffer is separate from the system clipboard. Either turn on set-clipboard, install tmux-yank, or use xclip/pbcopy explicitly.
"My vi-mode bindings don't work." Check setw -g mode-keys vi in your config, and reload (chapter 7). Some distros default to emacs.
"I can't leave copy mode." q in vi mode. Esc also usually works. If you've rebound those, try <prefix> [ again; repeated enter toggles out in some setups.
"Selection jumps around as I move." In some versions, the first motion after v expands the selection in a surprising direction. Experiment with rectangle-toggle (v in some modes) if you want a block selection.
Next Steps
Continue to 06-command-mode.md to learn the command prompt behind every tmux binding.