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

11 November 2026 · Daniel Bilsborough · Reviewed 11 November 2026

Quick answer: press Ctrl-b then [ to enter copy mode, scroll with Page Up or the arrow keys, and press q to go back. Ctrl-b Page Up does the first two in one step.

To scroll with a mouse wheel, a trackpad or a finger instead, put set -g mouse on in ~/.tmux.conf. The rest of this page covers why the normal scroll doesn't work, searching, keeping more history, and scrolling Tmux on a phone.

Why your terminal's scroll doesn't work in Tmux

Tmux draws its own screen inside your terminal and redraws it in place. The output that scrolls off the top goes into Tmux's history for that pane, not into your terminal app's scrollback. So scrolling the terminal window shows whatever was there before Tmux started, or nothing at all.

Two ways into Tmux's own history: copy mode with the keyboard, and mouse mode for wheels, trackpads and touch.

Copy mode: scrolling with the keyboard

Ctrl-b [ enters copy mode. A position indicator appears at the top right, and the pane stops following new output until you leave. Moving around depends on the key style. Tmux uses emacs-style keys unless the EDITOR or VISUAL environment variable contains "vi" when the server starts, in which case it picks vi keys. tmux show -gw mode-keys tells you which one you have.

ActionEmacs keys (default)Vi keys
Line up / downUp / Downk / j, or Up / Down
Page up / downPage Up / Page DownCtrl-b / Ctrl-f, or Page Up / Page Down
Half page up / downAlt-Up / Alt-DownCtrl-u / Ctrl-d
Top / bottom of historyAlt-< / Alt->g / G
Leave copy modeq or Escq

To use vi keys regardless of EDITOR, add setw -g mode-keys vi to ~/.tmux.conf.

Copying text out of the scrollback

In copy mode, move to the start of the text and begin a selection (Ctrl-Space with emacs keys, Space with vi keys), move to the end, then copy (Alt-w, or Enter with vi keys). Ctrl-b ] pastes it into the current pane. With set -g set-clipboard on, the copy can also reach the clipboard of the device you're connected from, if that terminal supports it.

Inside copy mode:

ActionEmacs keysVi keys
Search up (older output)Ctrl-r?
Search downCtrl-s/
Next match / previous matchn / Nn / N

The emacs-key searches are incremental, so the view jumps to matches as you type. For a long hunt, it can be easier to dump the whole history to a file and use grep or less:

tmux capture-pane -p -S - > ~/pane-history.txt

-S - starts from the oldest line in the history, and -p prints it rather than storing it in a Tmux buffer. Add -t name to capture a pane in another session.

Mouse mode: scrolling with a wheel, trackpad or finger

# ~/.tmux.conf
set -g mouse on

Then reload the config so the running server picks it up:

tmux source-file ~/.tmux.conf

With mouse mode on, scrolling up in a pane enters copy mode and scrolls the history, and scrolling back down to the bottom leaves copy mode again. Programs that ask for the mouse themselves, like vim or htop with mouse support on, get the scroll instead. Mouse mode also lets you click to pick a pane or window and drag pane borders to resize.

The trade-off: dragging now selects text in Tmux's copy mode rather than in your terminal app, so the selection goes to a Tmux buffer. Many desktop terminals have a modifier key that bypasses Tmux and selects with the terminal instead; it differs by app.

Keeping more scrollback: history-limit

Tmux keeps 2,000 lines per pane by default. Build logs and AI agent sessions blow through that quickly. Raise it in ~/.tmux.conf:

set -g history-limit 50000

The limit is set when a pane is created, so existing panes keep their old limit. Open a new window, or start a new session, to get the bigger history. Each line of history uses memory on the server, so very large limits across many panes add up.

To empty the history of the current pane, press Ctrl-b : and run clear-history.

Scrolling Tmux on an iPhone or iPad

A touchscreen has no Page Up key and no scroll wheel, which makes mouse mode the practical route. In Shell Drop:

Copy mode still works from the phone: tap Ctrl on the keyboard toolbar, then b, then [, and use the toolbar arrows. The swipe does the same job in one gesture. The Tmux cheat sheet has the other config lines worth adding for phone use, and Tmux attach and detach covers getting back into a session after a dropped connection.

Questions

How do I scroll up in tmux?

Press Ctrl-b then [ to enter copy mode, then use Page Up, the arrow keys, or Ctrl-b Page Up to jump straight in a page up. Press q to leave. For scrolling with a mouse, trackpad or swipe, add set -g mouse on to ~/.tmux.conf.

Why can't I scroll in tmux with my mouse wheel or trackpad?

Tmux keeps its own history, and with mouse mode off (the default) scroll events never reach it. Add set -g mouse on to ~/.tmux.conf and run tmux source-file ~/.tmux.conf.

How do I search the tmux scrollback?

Enter copy mode with Ctrl-b [. With the default keys, Ctrl-r searches up and Ctrl-s searches down. With vi keys, ? searches up and / searches down. n repeats the search and N reverses it.

How many lines of scrollback does tmux keep?

2,000 lines per pane by default. Raise it with set -g history-limit 50000 in ~/.tmux.conf. The new limit applies to panes created after the change.

How do I scroll tmux on an iPhone or iPad?

With set -g mouse on on the server, a vertical swipe in Shell Drop scrolls the Tmux history. Without it, Shell Drop shows a notice with a Show me how link to the line to add. On iPad the trackpad scrolls the history too.

Get Shell Drop on the App Store QR code for Shell Drop on the App Store Reading on a computer? Scan the code with your iPhone camera.