How to scroll up in tmux: mouse, copy mode and scrollback

Scroll with the mouse

tmux keeps its own history for each pane. Your terminal's scrollback only sees what tmux draws on the screen, so terminal shortcuts like Shift-PageUp never reach the tmux history. Use the mouse or copy mode instead.

Mouse support is on by default since tmux 3.8. On 3.7 and older, add set -g mouse on to ~/.tmux.conf and reload it. Debian 13, for example, still ships tmux 3.5a, where the option is off:

tmux show -g mouse
echo 'set -g mouse on' >> ~/.tmux.conf
tmux source-file ~/.tmux.conf

With the mouse on, the wheel over a pane enters copy mode and scrolls 5 lines per step. Scroll back to the bottom and tmux leaves copy mode on its own. Dragging with the left button selects text and copies it when you let go, a double-click copies a word and a triple-click copies a line.

Full-screen programs and programs that capture the mouse, such as vim or less, get the wheel events themselves instead of tmux.

Scroll with the keyboard (copy mode)

Press Ctrl-b [ to enter copy mode, or Ctrl-b PgUp to enter it and scroll up one page at once. Press q to leave; Escape also works with the default emacs keys and Ctrl-c with vi keys.

Copy mode uses emacs keys unless $VISUAL or $EDITOR contains "vi". To force vi keys, put set -g mode-keys vi in ~/.tmux.conf. These are the default bindings in tmux 3.8, checked with tmux list-keys -T copy-mode and -T copy-mode-vi:

The Ctrl-b and Ctrl-f page keys of vi mode clash with the default prefix, because tmux reads Ctrl-b as the prefix first. Use PgUp and PgDn instead.

Select and copy text

In emacs mode, Ctrl-Space starts a selection and Alt-w copies it and leaves copy mode. In vi mode, Space starts it and Enter copies and leaves.

In vi mode, v toggles rectangle selection instead of starting a selection, and y is not bound at all. Three lines in ~/.tmux.conf make it work like vim, with rectangle selection left on Ctrl-v:

set -g mode-keys vi
bind -T copy-mode-vi v send -X begin-selection
bind -T copy-mode-vi y send -X copy-selection-and-cancel

Ctrl-b ] pastes the most recent copy into the pane and Ctrl-b = opens a list of older ones. tmux keeps up to 50 paste buffers by default (buffer-limit).

The set-clipboard option defaults to external, so tmux also tries to put each copy on your system clipboard with the OSC 52 escape sequence. That only works if your terminal supports it and allows it.

Keep more scrollback

history-limit defaults to 2,000 lines per pane, which a chatty build or log fills fast. Raise it in ~/.tmux.conf; more history means more memory per pane.

echo 'set -g history-limit 50000' >> ~/.tmux.conf
tmux source-file ~/.tmux.conf
tmux display -p '#{history_size}/#{history_limit}'

Since tmux 3.7, a new history-limit also applies to panes that already exist. On older versions only new panes get it: on tmux 3.5a the last command still printed 278/2000 for an open pane, while tmux 3.8 printed 278/50000.

Save the scrollback to a file

tmux capture-pane -p -S - > scrollback.txt writes the whole history plus the current screen to a file. Add -J to join wrapped lines, -e to keep colors as escape codes, or -t NAME to read another session's pane.

To log output as it happens, tmux pipe-pane -o 'cat >> ~/pane.log' appends everything the pane prints from now on, and running the same command again turns it off.

tmux capture-pane -p -J -S - -t train > scrollback.txt
tmux pipe-pane -o -t train 'cat >> ~/pane.log'

If you mostly scroll back through a long job to see how far it got or whether it failed, you do not need the scrollback at all.

All the other tmux keys are in the tmux cheat sheet, and screen's own copy mode is covered in the Linux screen command guide.