tmux scroll and copy mode: scroll up, search, copy and paste

How to scroll up and down in tmux

Copy mode freezes the pane's view so you can move around its history: the program keeps running and its new output is kept, but the screen stops following it until you leave. An indicator in the top right shows where you are, for example [39/61]: 39 lines up from the bottom of 61 lines of history.

Real screenshot · tmux 3.8

The wheel scrolls 5 lines per notch, and scrolling back down to the bottom leaves copy mode by itself. In full-screen programs such as Vim, less or htop, the wheel goes to the program instead (since tmux 3.6), because they use the terminal's alternate screen and have no tmux history to scroll.

Want PgUp without the prefix? These lines make the bare keys enter copy mode and scroll, and leave it again at the bottom:

bind -n S-PPage copy-mode -eu
bind -n S-NPage copy-mode -ed

That binds Shift+PgUp / PgDn; many terminals use those keys themselves, so check yours passes them through.

vi or emacs keys

The default is emacs keys, unless your VISUAL or EDITOR environment variable contains "vi" when the tmux server starts. With EDITOR=nvim or EDITOR=vim you already get vi keys, which is why two people's copy mode can behave differently with the same config. The setting picks between two key tables, copy-mode-vi and copy-mode; the full side-by-side list is below.

setw -g mode-keys vi

How to search the scrollback

Three things we checked on tmux 3.8 that are worth knowing:

• Case: a search in all lowercase ignores case (error finds ERROR); any capital letter makes it exact (Error does not).
• Regular expressions: the vi / and ? searches are regular expressions, so E.*one matches ERROR one. Escape ., * and [ to match them literally.
• Match count: the indicator shows how many matches were found, for example (3 results).

If your shell marks its prompts with the OSC 133 escape sequence (many shell-integration scripts do), the emacs keys Ctrl+Alt+↑ and Ctrl+Alt+↓ jump from one command's prompt to the next; without those marks they do nothing.

How to select and copy text

setw -g mode-keys vi
bind -T copy-mode-vi v send -X begin-selection
bind -T copy-mode-vi C-v send -X rectangle-toggle
bind -T copy-mode-vi y send -X copy-pipe-and-cancel

copy-pipe-and-cancel with no command is what the default Enter runs: it copies to a buffer, sends the text to the clipboard where possible, pipes it to copy-command if you set one, and leaves copy mode. Use copy-pipe to stay in copy mode, or copy-pipe-no-clear to also keep the selection. Every copy command takes -P (do not create a paste buffer) and -C (do not send to the clipboard).

Rectangle selection copies a column of text, for example one field from a table of output. In tmux 3.8 the rectangle can also extend past the end of short lines, like Vim's virtualedit=block.

How to paste

Ctrl+b ] runs paste-buffer -p. The -p wraps the text in bracketed-paste codes when the program asks for them, so shells and editors know it is a paste: multi-line text is not run line by line, and Vim does not auto-indent it. With the mouse on, a middle click pastes too. tmux has no undo for a paste; in bash and zsh, Ctrl+u clears the line you have not yet run.

Paste buffers: list, choose, save and delete

Every copy creates a new buffer (buffer0, buffer1 …), and tmux keeps the last 50 (buffer-limit). Buffers belong to the server, so you can copy in one session and paste in another.

Real screenshot · tmux 3.8

$ echo "deploy@10.0.4.12" | tmux load-buffer -
$ tmux list-buffers
buffer0: 17 bytes: "deploy@10.0.4.12\n"
$ tmux save-buffer - | wc -c
17

Copy to the system clipboard (local and over SSH)

Option 1: OSC 52 through your terminal (works over SSH)

With set-clipboard at its default of external, tmux writes the copied text to the terminal as an OSC 52 escape sequence whenever the terminal description has the Ms capability. tmux adds it for any TERM starting with xterm (the default terminal-features), and since 3.6 it also detects OSC 52 support from the terminal's reply to a device attributes query. Because the escape sequence travels with the rest of the output, it works through SSH, mosh and nested tmux without any tool on the server.

What your terminal needs:

• Accept OSC 52 writes. kitty, WezTerm, Alacritty, foot, Ghostty and Windows Terminal do by default. iTerm2 needs Applications in terminal may access clipboard turned on in its settings. xterm needs the disallowedWindowOps resource changed (see man tmux under set-clipboard).
• A TERM tmux recognizes, or a line telling tmux. If your outer TERM does not start with xterm and copies do not arrive, add the feature for it:

# replace "alacritty" with the value of $TERM outside tmux
set -as terminal-features ',alacritty:clipboard'
# let programs inside tmux (Neovim, a nested tmux) set the clipboard too
set -s set-clipboard on

set-clipboard on also accepts OSC 52 from programs running inside tmux and turns it into a tmux buffer plus a clipboard write. You need it when Neovim's OSC 52 clipboard, or an inner tmux, should reach your local clipboard. off disables clipboard handling completely.

Option 2: pipe copies to a clipboard program

Set copy-command (tmux 3.2 and later) and every default copy key, including the mouse, pipes the text to it. This works only for the clipboard of the machine tmux runs on, so it is the right choice locally and the wrong one over SSH.

set -s copy-command 'pbcopy'

# Wayland (GNOME, KDE Plasma, Sway…): needs the wl-clipboard package
set -s copy-command 'wl-copy'
# X11: needs xclip (or use 'xsel -ib')
set -s copy-command 'xclip -selection clipboard -in'

set -s copy-command 'clip.exe'

For a key that copies to the clipboard program without changing the defaults, give the command to copy-pipe-and-cancel directly, for example bind -T copy-mode-vi y send -X copy-pipe-and-cancel 'pbcopy'. The tmux-yank plugin wraps the same idea and picks the right tool per system; see plugins.

The other direction, from the system clipboard into a tmux buffer, is tmux refresh-client -l: it asks the terminal for its clipboard with OSC 52, which only terminals that allow clipboard reads answer.

Copy and paste with the mouse

With the mouse on (default in 3.8), tmux handles mouse selection itself, so selections stay inside one pane instead of running across splits.

The terminal's own selection (with Shift) copies whatever is on screen, borders and neighboring panes included, but it uses the terminal's clipboard directly, so it works even when OSC 52 does not. To keep the selection when you let go, so you can adjust it and copy with a key:

bind -T copy-mode-vi MouseDragEnd1Pane send -X copy-pipe-no-clear
bind -T copy-mode MouseDragEnd1Pane send -X copy-pipe-no-clear

To turn tmux mouse handling off and get your terminal's selection back everywhere: set -g mouse off.

Line numbers in copy mode (tmux 3.7)

tmux 3.7 can number the lines in copy mode, which helps with goto-line (: in vi, g in emacs) and with telling someone "look at line 42".

# off | default | absolute | relative | hybrid
setw -g copy-mode-line-numbers relative

absolute counts from the first line of history, relative from the cursor (like Vim's relativenumber), and hybrid shows the current line absolute and the rest relative. With emacs keys, L toggles numbers; with vi keys bind one, for example bind -T copy-mode-vi L send -X line-numbers-toggle. Numbers stay off when you enter copy mode with the mouse wheel.

Watch new output in copy mode (tmux 3.8)

Normally the copy mode view is frozen. In tmux 3.8, r refreshes it once from the pane, and the new refresh-on, refresh-off and refresh-toggle commands keep it updating as output arrives. It is off by default; when on, it scrolls only while the cursor is at the bottom and pauses while you are selecting.

bind -T copy-mode-vi R send -X refresh-toggle

The right-click menu in copy mode has Refresh On / Refresh Off too. These replace the older refresh-from-pane command.

Every copy mode key: vi and emacs side by side

The full default key tables of tmux 3.8, generated from tmux list-keys. Type in the filter to find a key or an action. For the prefix keys that enter and leave copy mode, see the cheat sheet.

Generated from the default copy-mode-vi (88 bindings) and copy-mode (78 bindings) key tables of tmux 3.8, with no config file. Mouse bindings are listed separately in the mouse section. See them yourself with tmux list-keys -T copy-mode-vi.

Any key can be rebound with bind -T copy-mode-vi key send -X command (or -T copy-mode for emacs). The commands are the names in the last column; man tmux lists all of them under "WINDOWS AND PANES".

Scrollback size: history-limit and clearing history

set -g history-limit 50000

On tmux 3.7 and later, changing history-limit also applies to panes that are already open. On 3.4 and other older versions it only affects panes created afterwards, so put it in your config before tmux starts (or restart the server). The history is kept in memory for every pane, so very large limits across many panes add up; 10,000 to 100,000 lines is a common range.

To wipe a pane's history, run tmux clear-history (-t for another pane). clear or Ctrl+l in the shell only clears the screen; the lines are still in tmux's history. To do both:

$ clear && tmux clear-history

Save the scrollback to a file

# whole history plus the visible screen
$ tmux capture-pane -p -S - > scrollback.txt
# only the last 100 lines
$ tmux capture-pane -p -S -100 > last100.txt
# join lines that were wrapped by the pane width
$ tmux capture-pane -p -J -S - > joined.txt
# keep colors (ANSI escape sequences); view with less -R
$ tmux capture-pane -p -e -S - > colored.txt
# another pane: session work, window 1, pane 0
$ tmux capture-pane -p -S - -t work:1.0 > other.txt
# line numbers (3.7) and the time each line entered the history (3.8)
$ tmux capture-pane -p -L -S -3
$ tmux capture-pane -p -I -S -3

Line numbers count back from the visible screen (-2, -1, 0), and -I prints a Unix timestamp before each history line (0 for lines still on screen). To record everything a pane prints from now on, rather than what is already there, use pipe-pane:

$ tmux pipe-pane -o 'cat >> ~/tmux-#{session_name}.log'
# run the same command again (or with no command) to stop
$ tmux pipe-pane

Capturing from scripts, polling output and the other flags are covered in tmux scripting.

When scrolling or copying does not work

More fixes for clipboard, mouse and frozen panes are in tmux troubleshooting.

Frequently asked questions