How do I scroll with either the keyboard or mouse? The tmux man page indicates one must enter copy-mode to scroll. Is there a way to quickly scroll without manually entering copy-mode?

Mateen Ulhaq
  • 3,452
  • 6
  • 35
  • 56
  • 19,369
  • 3
  • 16
  • 9

15 Answers15


Ctrl-b then [ then you can use your normal navigation keys to scroll around (eg. Up Arrow or PgDn). Press q to quit scroll mode.

Alternatively you can press Ctrl-b PgUp to go directly into copy mode and scroll one page up (which is what it sounds like you will want most of the time)

In vi mode (see below), you can also scroll the page up/down line by line using Shift-k and Shift-j (if you're already in scroll mode). Unshifted, the cursor moves instead of the page.

Excerpts from the man page:

tmux may be controlled from an attached client by using a key combination of a prefix key, ‘C-b’ (Ctrl-b) by default, followed by a command key.

 The default command key bindings are:

[           Enter copy mode to copy text or view the history.

Function                     vi              emacs
--------                     --              -----
Half page down               C-d             M-Down
Half page up                 C-u             M-Up
Next page                    C-f             Page down
Previous page                C-b             Page up
Scroll down                  C-Down or C-e   C-Down
Scroll up                    C-Up or C-y     C-Up
Search again                 n               n
Search again in reverse      N               N
Search backward              ?               C-r
Search forward               /               C-s

Plus a bunch more. Note that you have to press C-b twice if you use that for page up since C-b is bound as the command key. See the man page for information on prefacing a copy mode command with a repeat count.

You can set the key binding mode using Ctrl-b, then

:set-window-option mode-keys emacs

or vi.

Dennis Williamson
  • 106,229
  • 19
  • 167
  • 187
  • 22
    I think `C-b =` is `choose-buffer` by default. Did you mean `C-b [` (which is `copy-mode` by default)? Also you can also use `C-b PageUp` to start copy-mode directly on the previous page (very handy when you know what you want to view/copy has already scrolled off the current page). – Chris Johnsen Nov 11 '10 at 05:55
  • 1
    @Chris: In my tmux 0.8 (and its man page), `C-b =` is `scroll-mode`. [Apparently](http://tmux.cvs.sourceforge.net/viewvc/tmux/tmux/CHANGES), newer versions have dropped that. – Dennis Williamson Nov 11 '10 at 11:53
  • 1
    Ahh, that explains it. I think I started with 1.1 which was already after `scroll-mode` had been subsumed. The OP says ‘only two instances of the word "scroll" [in the man page]’, so the version is probably one without `scroll-mode`. – Chris Johnsen Nov 11 '10 at 12:22
  • 5
    Correct, my tmux has no scroll-mode. You need to `C-b [` to enter copy mode and then use either the emacs or vi key-bindings to scroll around. This seems like a lot of steps just to scroll, but the benefits of tmux still outweigh these annoyances. I'm on a macbook and there is no PageUp key :-\. (Also, how do I make keys with markdown like you did, Dennis?) – chadoh Nov 11 '10 at 17:11
  • 52
    @chadoh: Try these on your Macbook: Home: fn-LeftArrow; End: fn-RightArrow; Page Up: fn-UpArrow; Page Down: fn-DownArrow. To make keycaps: `Ctrl` – Dennis Williamson Nov 11 '10 at 18:43
  • 6
    on macbook, the fn+up goes straight to terminal app and never hits tmux – Tyler Apr 11 '11 at 17:57
  • 17
    On a macbook if you're in scroll mode you can use fn+Shift+LeftArrow to scroll up a page. – Nick Hammond May 18 '13 at 17:51
  • With vi mode-keys you can also use it's typical: C-y and C-e to scroll up/down line by line – wik Jul 29 '13 at 12:07
  • @chaiyachaiya's answer is much better (If you can bear to reach for the mouse) – Jonathan Hartley Nov 04 '13 at 09:44
  • 2
    To escape from scroll mode, press Escape or Q. Don't get stuck like I did :) – Graham Perks Feb 04 '15 at 01:59
  • Isn't there a better way than just up and down arrows to scroll tmux? Like batch scrolling as in ctrl+b similar to VIM? – Charlie Parker Jan 26 '16 at 00:34
  • 1
    @CharlieParker: I've expanded my answer to include some navigation key bindings. Note that you can use numeric count prefixes like you would in `vim` so (set to vi key bindings) you could press `2` then `PageUp` (or `Ctrl-b` (twice)) and you'd move up two screen fulls. – Dennis Williamson Jan 26 '16 at 00:52
  • 2
    So much hassle just to accomplish basic stuff - why UI has to be so poor? – Dima Knivets Apr 07 '16 at 12:22
  • Is `Shift-j` and `Shift-k` line by line scrolling enabled by default? It seems like it is on my machine. – mbigras Apr 05 '17 at 16:13
  • @mbigras: It seems to be. – Dennis Williamson Apr 05 '17 at 16:16
  • @DennisWilliamson does that mean tmux is in vi mode by default? Or does it only have some of the functionality? Line by line scrolling in this case. – mbigras Apr 05 '17 at 16:18
  • @mbigras: From the man page: "mode-keys [vi | emacs] Use vi or emacs-style key bindings in copy mode. The default is emacs, unless VISUAL or EDITOR contains 'vi'." – Dennis Williamson Apr 05 '17 at 16:30
  • @DennisWilliamson thank you! Makes sense, `$echo $EDITOR #=> vim` what did you search for in the man page? For example, `:/foobar` – mbigras Apr 05 '17 at 16:32
  • @mbigras I searched for "mode-keys" and looked around. – Dennis Williamson Apr 05 '17 at 16:55
  • 1
    To escape, type in `Q` or `Ctrl` + `J`. – Mateen Ulhaq May 02 '17 at 17:35
  • 1
    `CTRL-B` and then `PgUp` is working fine. Then I can use `PgUp`, `PgDn` or `ArrUp`, `ArrDn`. To leave and auto scroll to the end hit `Esc` – Markus Zeller Nov 17 '18 at 16:44
  • I know this is sort of against the spirit but I want to use my mouse... – Charlie Parker Mar 25 '21 at 22:25
  • @CharlieParker: https://gist.github.com/paulodeleo/5594773 (I haven't tested this) – Dennis Williamson Jun 27 '22 at 12:57
  • Keyboard short cuts for more: https://tmuxcheatsheet.com/ – Convexity May 19 '23 at 07:33

Well, you should consider the proper way to set scrolling: add in your ~/.tmux.conf

set -g mouse on        #For tmux version 2.1 and up


set -g mode-mouse on   #For tmux versions < 2.1

It worked for me in windows and panes. Now tmux is just perfect.

Practical tmux has more info on tmux.conf files.

  • 9,516
  • 25
  • 116
  • 172
  • 5,079
  • 1
  • 12
  • 2

From my .tmux.conf:

# Sane scrolling
set -g terminal-overrides 'xterm*:smcup@:rmcup@'

This enables native xterm scrolling.

  • 1,967
  • 1
  • 11
  • 4
  • 41
    Can you explain what this does exactly? – Ivo Oct 31 '11 at 06:25
  • 8
    This doesn't work for me on OS X... – Nick Apr 17 '12 at 13:56
  • 17
    Solution: https://gist.github.com/1297707 – Nick Apr 17 '12 at 15:25
  • 9
    Check this out if you're confused about togdon's answer: http://superuser.com/questions/310251/use-terminal-scrollbar-with-tmux?lq=1 IMO, if you have only a single pane, this solution works better than the accepted answer. – thameera Apr 16 '13 at 07:48
  • 2
    Nice, but it breaks (for me) after displaying some file using the `less` command, i.e., the mouse wheel scrolling up will display N empty lines, where N=length of file displayed with `less`. – dehmann Nov 07 '13 at 22:11
  • Works as expected in ubuntu. Pgup and Pgdn keys enable you to scroll. Thanks. – Shnkc Feb 05 '14 at 09:55
  • This is really weird. If you look at the scroll bar, it stays at the top until you start scrolling; then it shoots to the top. I am kind of glad this works, though. – dylnmc Apr 17 '15 at 07:42
  • 3
    https://wiki.archlinux.org/index.php/Tmux#Scrolling_issues – Brian Maltzan Jun 20 '15 at 16:39
  • I thought it was working at first, but in the end I had to disable it, it sometimes messes my output. – nha Jul 03 '15 at 09:15
  • 2
    It doesn't keep the scrollback buffer after a(n) (re)attach – Ray Jan 21 '16 at 09:39
  • 2
    This does not work for multiple panes. It will scroll the main host terminal instead of the emulated terminals running inside of tmux – Shadoninja May 04 '16 at 22:48
  • This works for me on OS X. For `screen` I used to do something similar in my `.screenrc` as well to achieve the same effect: `termcapinfo xterm* ti@:te@` – nishanthshanmugham May 22 '16 at 07:37
  • 1
    This, no longer seem to work. When I scroll the output is missing lines and is incomplete. – Ashesh Nov 01 '17 at 17:14
  • For newer versions the answer below mine is the correct one. – togdon Nov 03 '17 at 21:49
  • Scroll-up gets completely broken (garbage text), with this enabled. – chefarov Mar 19 '19 at 17:53

For the newest tmux 2.1, to scroll with your mouse sanely, this is the right answer:

set -g mouse on
# sane scrolling:
bind -n WheelUpPane if-shell -F -t = "#{mouse_any_flag}" "send-keys -M" "if -Ft= '#{pane_in_mode}' 'send-keys -M' 'copy-mode -e; send-keys -M'"

it's not enough to just reload your .tmux.conf you need to restart your tmux, e.g. tmux kill-server && tmux or just quit the services that are using tmux.

taken from https://github.com/tmux/tmux/issues/145

  • 103
  • 5
  • 1,031
  • 7
  • 5
  • 2
    the note in this answer about "not being enough to simply reload .tmux.conf helped" and exiting all tmux sessions for me (maybe kill-server would work) helped! – Colin D Jan 25 '17 at 18:05
  • 3
    could you elaborate on how this works? – oligofren Jul 19 '17 at 07:31
  • It appears to forward mouse events when the mouse is clicked/scrolled/etc. if the pane is in any indirect/buffered state (just copy-mode?), and the mouse is pressing a button, scrolling, etc. The last portion covers scrolling in direct mode by switching to an indirect mode first. If not for those controls, the terminal might interpret the events as history scrolling, if at all. With that said, I don't know if I've ever been able to get my pager and Vim to scroll correctly at the same time, and I've tried a bunch of the snippets going around. – John P Jan 02 '18 at 14:13
  • you can't select and copy text with your mouse when `set -g mouse on` is enabled – chefarov Mar 19 '19 at 17:54
  • 3
    @chefarov - per a comment on another answer, you can do this via `Shift+click` when you have mouse mode on. – Brendan Moore Mar 27 '19 at 13:23
  • Commands' output that's longer than the screens height, is trancated when scrolling up if `set -g mouse on` is set. – chefarov Mar 30 '19 at 18:08
  • great that " hack for #macos " was ```tmux kill-server``` – Bruno Jul 31 '23 at 20:25

In my case, just opt + UpArrow and opt + DownArrow on OSX.

  • 3,848
  • 3
  • 30
  • 47
  • 341
  • 2
  • 3

This is the way I made it work, and the reasons why I think it is better than the default way.

To try it out, put all the code sections in ~/.tmux.conf.

Step 1. Change the prefix key so you won't have to reach one bit. 'B' is seemingly a close key, but it is in the middle of the two index fingers (at 'F' and 'J', respectively). Because that shortcut is essential in tmux, C-j is much better as it involves zero hand movement (apart from hitting the key).

set -g prefix C-j
unbind C-b
bind C-j send-prefix

Step 2. 'S' (to enter copy-mode) is: 1) close (same reason as above), 2) involves the other hand (compare: the 1-2 in boxing, or the ls command to view files in a directory), and 3) could be thought of as mnemonic for "scroll" (although the copy-mode isn't just about scrolling).

bind s copy-mode

Step 3. The last part, the actual scrolling. 'P' and 'N' are familiar for this purpose to the Emacs users. They are close, intuitive ('P' is above 'N' on the keyboard), and mnemonic ("previous" and "next"). If you just did some scrolling in Emacs, and then go to tmux, it makes sense to have those shortcuts.

However, I found that 'I' and 'K' are even better - they are even closer than 'P' and 'N', and intuitive (for the same reason); as for mnemonics - as scrolling is such a common thing to do, mnemonics won't really matter as the shortcuts will soon bypass your brain and enter the muscle memory.

bind -t emacs-copy 'p' scroll-up
bind -t emacs-copy 'n' scroll-down
bind -t emacs-copy 'i' scroll-up
bind -t emacs-copy 'k' scroll-down
Emanuel Berg
  • 509
  • 6
  • 11

This worked for me:

vim ~/.tmux.conf
set -g mode-mouse on      ###Insert this setting with vim, then source the file.
tmux source-file ~/.tmux.conf
  • 151
  • 1
  • 2
  • 5
    Since the version 2.1 (18 October 2015) the option should be `set -g mouse on` – naoko Dec 27 '18 at 00:07
  • 1
    +1 since this solution worked without restarting the tmux server (I had important jobs running). I did detach and reattach to the tmux session though. Remember the change of `set -g mode-mouse on` to `set -g mouse on` appropriately as mentioned in the @naoko 's comment. – tu_curious Jul 21 '21 at 18:22
  • Very helpful. The sourcing of the config file was missing in other answers. Thanks! – normanius May 31 '22 at 08:13

I'd recommend giving a try to the tmux-better-mouse-mode plugin to solve most of your tmux mouse related issues.

It's compatible with Tmux 2.1+ and the new set-option -g mouse on approach.

  • 221
  • 3
  • 4
  • 1
    Thanks, this is the best solution for me. It covers all my mouse wheel bindings that I've added manually (so I don't need them anymore), and there are two killer-features that I wanted very much: `scroll-without-changing-pane` in combination with `scroll-without-changing-pane` and `emulate-scroll-for-no-mouse-alternate-buffer`. Now my tmux usage experience is way, way better. – selurvedu Jun 05 '18 at 11:02

I searched around a lot for this and the best solution for me works as mentioned in this detailed guide: http://tangledhelix.com/blog/2012/07/16/tmux-and-mouse-mode/

Add these bindings in ~/.tmux.conf:

set -g mode-mouse on

unbind +
bind + \
  new-window -d -n tmux-zoom 'clear && echo TMUX ZOOM && read' \;\
  swap-pane -s tmux-zoom.0 \;\
  select-window -t tmux-zoom

unbind -
bind - \
  last-window \;\
  swap-pane -s tmux-zoom.0 \;\
  kill-window -t tmux-zoom

With the above approach implemented, you can copy from panes in a window as well by zooming into each pane first using Prefix +.

One important detail that was missing with the mouse mode is to press Shift before selecting an area to copy. This will copy it to traditional terminal buffer instead of the tmux copy buffer. (https://wiki.archlinux.org/index.php/Tmux#Scrolling_issues)

  • 121
  • 1
  • 7

The only thing that works for me is putting the following in ~/.tmux.conf

# Allow xterm titles in terminal window, terminal scrolling with scrollbar, and setting overrides of C-Up, C-Down, C-Left, C-Right
set -g terminal-overrides "xterm*:XT:smcup@:rmcup@:kUP5=\eOA:kDN5=\eOB:kLFT5=\eOD:kRIT5=\eOC"

(you may need to reboot for this to take effect)


I found that if you change the setting in Putty Connection > Data > Terminal-type to "putty" (used to fix some formatting issues) from "xterm" then this solution stops working.

Update 2:

Use this if you want "putty" as your terminal type: set -g terminal-overrides "putty*:XT:smcup@:rmcup@:kUP5=\eOA:kDN5=\eOB:kLFT5=\eOD:kRIT5=\eOC"

  • 263
  • 3
  • 12

On OSX Mojave and newer, after entering copy mode with ctrl + b [, you can do:

  • up arrow for line up
  • down arrow for line down
  • fn + up arrow for page up
  • fn + down arrow for page down
  • q to quit copy mode
  • 123
  • 7
  • 201
  • 2
  • 3

The top answers already explain how to scroll. I'd like to add an option to avoid the need for scrolling: Pipe the output of long commands into less. less is a program to navigate through text files.

superlongcommand | less

Then you can use vim-like bindings (d/u) or PgUp/PgDn to scroll and q to exit. See Less Cheatsheet


Host + [ mine key is Ctrl + a the default key is Ctrl + b

after that its easy to navigate with vim config

  • 2,189
  • 1
  • 14
  • 32

The answers above did not work for me to enable keyboard scrolling, but this answer from a different question worked:

bind -n Pageup copy-mode -u
bind -n S-Pageup copy-mode -u
bind -n S-Pagedown send-keys Pagedown
  • 191
  • 1
  • 3
  • Ctrl + A - to start scrolling
  • Ctrl + C - to stop scrolling
  • 18,569
  • 15
  • 57
  • 68
  • 5
    This post is too short to be usefully answer the question. It adds very little new information to answers already posted; it says nothing about *how* to scroll (only how to change in and out of copy mode). Also, the default command prefix key combination is `Ctrl-B` (`Ctrl-A`is the default for GNU screen). – Anthony Geoghegan Oct 26 '16 at 08:50
  • 3
    Not sure if the author of this answer even understood the question. It's unhelpful and just wrong. – Vik Mar 30 '17 at 07:53
  • 2
    I've been looking for how to stop scrolling for so long, thanks for pointing it out! – PERR0_HUNTER Apr 09 '17 at 17:12