Most tmux users scroll with a mouse and lose everything to the scrollbar. Copy mode turns the keyboard into a full vi-style browser over your scrollback — searchable, copyable, pipeable.
Once a pane’s output scrolls off screen, a terminal loses it; tmux doesn’t — it keeps a scrollback buffer per pane, and copy mode is the interface to it. Enter it with prefix-[ (that’s Ctrl-b then [) and the pane freezes into a scrollable document you drive with vi keys: j/k to move, Ctrl-f/Ctrl-b to page, / to search downward, ? upward, n to repeat the search. Space starts a selection, Enter copies it into a paste buffer, and prefix-] pastes it into any pane. That last hop is the whole point: copied text lives inside tmux, so it works over SSH where OS clipboards can’t reach, and the buffer is a first-class object you can list, save to a file, or pipe into another command. Turn the keymap on permanently with one line in ~/.tmux.conf: # vi keys in copy mode — put this in ~/.tmux.conf set -g mode-keys vi
set is short for set-option. tmux works out on its own that mode-keys is a window option, so you don’t need the older set-window-option (setw) spelling. tmux stopped documenting that name in 3.0. It is still accepted, but the current manual only describes set.
install
# macOS
brew install tmux
# Debian/Ubuntu
sudo apt install tmux
# Fedora
sudo dnf install tmux
# Arch
sudo pacman -S tmux
examples
# Enter copy mode (then move with vi keys, q to quit) # press: Ctrl-b [ # Search scrollback for that one error from 400 lines up # in copy mode, press: / then type error, Enter, then n # Copy a command's output from the pane into a file # (select the lines with Space...Enter in copy mode, then:) tmux save-buffer -b buffer0 output.txt
# Pipe the most recent buffer into a local command instead of a file
tmux show-buffer | grep -n error
# Save the pane's whole history to a local file, with wrapped lines joined back together
tmux capture-pane -J -p -S - > pane-history.txt
# Grab the whole visible pane as text, without copy mode
tmux capture-pane -p > pane.txt
# Grab EVERYTHING the pane ever printed, not just the screen
tmux capture-pane -p -S - > all-history.txt
# List and inspect your paste buffers
tmux list-buffers
tmux show-buffer
pro tip
Mouse mode does the right thing with zero config: scroll-wheel up
drops you into copy mode and a click-drag selects, releasing to
copy. Combined with mode-keys vi you get the best of both — the
mouse to get there fast, the keyboard once you’ve arrived.
(set -g mouse on if it isn’t already.)
honest limits
Copy mode is per-pane: it sees that pane’s scrollback and nothing else, and buffers are wiped when the server exits — nothing here survives a reboot unless you save-buffer to a file first. It’s a terminal text viewer, not a pager: no syntax highlighting, no wrap-aware reflow, and very long wrapped lines stay wrapped. And if you live inside a full TUI app (vim, btop), copy mode will show you the character grid it drew — for real text out of those, use the app’s own yank/export.