Tmux Copy Mode: Yanking Text Across Panes Without Leaving the Keyboard

You ran a command in one tmux pane, and the error output you need is three scrolls up in another. Reaching for the mouse to select it breaks your flow and, worse, often grabs text across pane borders. Tmux copy mode solves this: it gives you a scrollback buffer with vi-style search and selection, so you can copy text from any pane and paste it anywhere in the session — or into the system clipboard — without leaving the keyboard.

What copy mode actually is

Every tmux pane keeps a scrollback history (default 2000 lines, configurable via history-limit). Copy mode freezes that buffer and lets you move through it, search it, mark a selection, and "yank" (copy) it into a tmux paste buffer. Paste buffers live inside tmux, so they survive pane switches and even session detaches — but they are separate from your OS clipboard unless you bridge them explicitly.

Prerequisites

• tmux 3.0 or newer (check with tmux -V; examples below assume 3.2+ behavior).
• A config file at ~/.tmux.conf you can edit, plus permission to reload it.
• For system clipboard integration: xclip or xsel on X11 Linux, wl-copy on Wayland, or pbcopy on macOS. On a headless SSH session to a remote host, none of these exist on the remote — see the limitations section.

Enable vi keys and clipboard integration

Add this to ~/.tmux.conf:

# Use vi keys in copy mode
set -g mode-keys vi

# Enter copy mode with Prefix + [
# (default binding; shown for clarity)
bind [ copy-mode

# v starts a selection, y yanks and pipes to the OS clipboard
bind -T copy-mode-vi v send -X begin-selection
bind -T copy-mode-vi y send -X copy-pipe-and-cancel "xclip -in -selection clipboard"

# Larger scrollback
set -g history-limit 50000

Replace xclip -in -selection clipboard with pbcopy on macOS or wl-copy on Wayland. copy-pipe-and-cancel copies the selection into tmux's buffer and pipes it to the external command, then exits copy mode. If you only want tmux-internal copying, use copy-selection-and-cancel instead and drop the external tool entirely.

Reload the config from inside tmux (Prefix is Ctrl-b by default):

tmux source-file ~/.tmux.conf

This runs as your normal user inside any pane and changes only the running server's config — low risk, and reversible by editing the file and reloading again.

The daily workflow

1. Press Prefix [ to enter copy mode in the active pane.
2. Search backward with ? followed by a pattern (e.g., ?ERROR), or forward with /. n jumps to the next match.
3. Move to the start of the text, press v, move to the end, press y. The selection is yanked and copy mode exits.
4. Paste into any pane with Prefix ] (tmux buffer) or your terminal's normal paste (if you piped to the OS clipboard).

Two selection variants worth knowing: Ctrl-v in copy mode toggles rectangle (block) selection — useful for grabbing a column out of aligned output — and send -X copy-line grabs a whole line without marking endpoints.

Verify it works

Run these checks inside a session:

# Confirm vi mode is active (should print "vi")
tmux show-options -g mode-keys

# Confirm your y binding exists (run from a shell, not copy mode)
tmux list-keys -T copy-mode-vi | grep copy-pipe

Then do an end-to-end test: echo a unique string, enter copy mode, yank it, and paste it into another pane with Prefix ]. If you configured clipboard piping, also paste into a GUI app outside the terminal to confirm the external tool received the text. If the tmux paste works but the system clipboard is empty, the external command is missing or failed silently — check which xclip (or your variant) on the machine where tmux runs.

Limitations and failure modes

• Remote/headless sessions: xclip on a remote server writes to the remote X display, not your laptop's clipboard. For SSH, the practical options are terminal-level selection with mouse mode off, or OSC 52 escape sequences (set -g set-clipboard on in tmux 3.2+, if your terminal supports it).
• Mouse conflicts: set -g mouse on lets you scroll into copy mode with the wheel, but it intercepts clicks that terminal apps (like Vim with mouse enabled) expect. Toggle it per-session with tmux set -g mouse off when an app misbehaves.
• Version drift: tmux 3.2 changed some default mouse and clipboard behavior. If an old config breaks after an upgrade, tmux list-keys -T copy-mode-vi is the fastest way to see what bindings actually exist.

None of these steps modify files outside ~/.tmux.conf, so recovery is simply editing the file and reloading — or restarting the tmux server with tmux kill-server if the config is badly broken (this ends all sessions, so save work first).