How do I scroll in tmux?

1 389

521

I just started using tmux, and I really like it, but I need to be able to scroll within the buffers/panes/windows I have open. I don't care if it works with the mouse or not. When I search the tmux man page, I find only two instances of the word "scroll" even showing up, and both have to do with copy mode. Is there a way to scroll without all the overhead of entering copy mode?

chadoh

Posted 2010-11-10T18:40:45.620

Reputation: 14 059

2for me you can press f7 for scroll mode and q to quit – JohnMerlino – 2014-07-25T14:56:53.993

8set -g mode-mouse on per @chaiyachaiya's answer was the winner for me – Peter Berg – 2016-07-21T19:36:31.247

8What overhead are you concerned with? copy-mode is the way to view history (and optionally copy stuff out of it). – Chris Johnsen – 2010-11-11T05:48:00.530

Answers

1 685

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.

Paused until further notice.

Posted 2010-11-10T18:40:45.620

Reputation: 86 075

1To escape from scroll mode, press Escape or Q. Don't get stuck like I did :) – Graham Perks – 2015-02-04T01:59:08.320

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 – 2016-01-26T00:34:29.400

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. – Paused until further notice. – 2016-01-26T00:52:25.903

1So much hassle just to accomplish basic stuff - why UI has to be so poor? – Dima Knivets – 2016-04-07T12:22:29.587

Is Shift-j and Shift-k line by line scrolling enabled by default? It seems like it is on my machine. – mbigras – 2017-04-05T16:13:17.290

@mbigras: It seems to be. – Paused until further notice. – 2017-04-05T16:16:43.850

@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 – 2017-04-05T16:18:53.937

@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'." – Paused until further notice. – 2017-04-05T16:30:45.950

@DennisWilliamson thank you! Makes sense, $echo $EDITOR #=> vim what did you search for in the man page? For example, :/foobar – mbigras – 2017-04-05T16:32:52.200

@mbigras I searched for "mode-keys" and looked around. – Paused until further notice. – 2017-04-05T16:55:53.030

1To escape, type in Q or Ctrl + J. – Mateen Ulhaq – 2017-05-02T17:35:09.517

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 – 2018-11-17T16:44:21.177

15I 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 – 2010-11-11T05:55:46.640

1

@Chris: In my tmux 0.8 (and its man page), C-b = is scroll-mode. Apparently, newer versions have dropped that.

– Paused until further notice. – 2010-11-11T11:53:09.723

1Ahh, 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 – 2010-11-11T12:22:26.383

4Correct, 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 – 2010-11-11T17:11:09.377

46@chadoh: Try these on your Macbook: Home: fn-LeftArrow; End: fn-RightArrow; Page Up: fn-UpArrow; Page Down: fn-DownArrow. To make keycaps: <kbd>Ctrl</kbd> – Paused until further notice. – 2010-11-11T18:43:15.533

5on macbook, the fn+up goes straight to terminal app and never hits tmux – Tyler – 2011-04-11T17:57:15.480

16On a macbook if you're in scroll mode you can use fn+Shift+LeftArrow to scroll up a page. – Nick Hammond – 2013-05-18T17:51:51.690

With vi mode-keys you can also use it's typical: C-y and C-e to scroll up/down line by line – wik – 2013-07-29T12:07:00.097

@chaiyachaiya's answer is much better (If you can bear to reach for the mouse) – Jonathan Hartley – 2013-11-04T09:44:26.040

335

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

or

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.

chaiyachaiya

Posted 2010-11-10T18:40:45.620

Reputation: 3 359

17Mouse scrolling works fine with this, but unfortunately I cannot use the mouse to select text anymore. Using Tilda and tmux. – friederbluemle – 2015-03-17T03:40:37.507

30Important note: This setting breaks highlighting and copying text. Use shift+click to maintain this functionality. – Shadoninja – 2016-05-04T22:50:36.677

@Mr.F try set mouse-utf8 off – Gareth Davidson – 2016-11-10T18:49:57.223

1>

  • we can no longer select text using clicks
  • we can't scroll into vim
  • < – pltrdy – 2017-11-27T15:54:16.200

    1This worked for me, but only after killing the tmux server with tmux kill-server. – Blaine Lafreniere – 2018-08-28T22:16:08.833

    1@pltrdy @friederbluemle @Shadoninja: with mode-mouse on use can still select text with Shift + mouse drag or Option + mouse drag on Mac. – ccpizza – 2019-04-24T20:27:49.223

    1Can't believe this took me so many years to find. – thedanotto – 2019-05-31T15:06:23.587

    Note for Windows Terminal (microsoft/terminal) users, this won't work until this issue is fixed.

    – Taylan – 2020-01-02T19:29:56.893

    5When I do this, mouse clicks and scrolls cause gibberish characters to be printed to the prompt area of the terminal I'm using with tmux. Any ideas? – ely – 2013-08-01T15:38:11.253

    This works great for me. Now if only we can figure key bindings to do the same (maybe a screen at a time), I'll be a very happy camper. – Jonathan Hartley – 2013-11-04T09:45:02.497

    26Future tmux mouse users: To save you having to scroll to the bottom again before typing, you can hit q to exit scroll mode. – Jezen Thomas – 2014-01-07T05:11:43.320

    147

    From my .tmux.conf:

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

    This enables native xterm scrolling.

    togdon

    Posted 2010-11-10T18:40:45.620

    Reputation: 1 587

    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 – 2015-04-17T07:42:46.943

    3https://wiki.archlinux.org/index.php/Tmux#Scrolling_issues – Brian Maltzan – 2015-06-20T16:39:53.413

    I thought it was working at first, but in the end I had to disable it, it sometimes messes my output. – nha – 2015-07-03T09:15:53.310

    1It doesn't keep the scrollback buffer after a(n) (re)attach – Ray – 2016-01-21T09:39:06.653

    2This does not work for multiple panes. It will scroll the main host terminal instead of the emulated terminals running inside of tmux – Shadoninja – 2016-05-04T22:48:23.070

    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@ – truncated – 2016-05-22T07:37:35.253

    1This, no longer seem to work. When I scroll the output is missing lines and is incomplete. – Ashesh Kumar Singh – 2017-11-01T17:14:19.757

    For newer versions the answer below mine is the correct one. – togdon – 2017-11-03T21:49:13.267

    Scroll-up gets completely broken (garbage text), with this enabled. – chefarov – 2019-03-19T17:53:53.633

    31Can you explain what this does exactly? – Ivo – 2011-10-31T06:25:01.130

    11I don't know what it does, but it is pure genius. Finally, tmux scrolling works, yay! – oneself – 2011-11-28T21:26:35.243

    6This doesn't work for me on OS X... – Nick – 2012-04-17T13:56:52.763

    17

    Solution: https://gist.github.com/1297707

    – Nick – 2012-04-17T15:25:04.150

    6

    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 – 2013-04-16T07:48:31.253

    2Nice, 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 – 2013-11-07T22:11:59.403

    Works as expected in ubuntu. Pgup and Pgdn keys enable you to scroll. Thanks. – Shnkc – 2014-02-05T09:55:20.753

    63

    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

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

    Flov

    Posted 2010-11-10T18:40:45.620

    Reputation: 731

    2How is this not the accepted answer? – Marcel – 2016-12-21T20:28:51.660

    2the 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 – 2017-01-25T18:05:51.223

    2could you elaborate on how this works? – oligofren – 2017-07-19T07:31:27.753

    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 – 2018-01-02T14:13:33.333

    you can't select and copy text with your mouse when set -g mouse on is enabled – chefarov – 2019-03-19T17:54:51.020

    3@chefarov - per a comment on another answer, you can do this via Shift+click when you have mouse mode on. – Brendan Moore – 2019-03-27T13:23:37.340

    @BrendanMoore True – chefarov – 2019-03-27T14:49:52.010

    Commands' output that's longer than the screens height, is trancated when scrolling up if set -g mouse on is set. – chefarov – 2019-03-30T18:08:14.977

    16

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

    ythdelmar

    Posted 2010-11-10T18:40:45.620

    Reputation: 261

    @fixer1234 The question does not mention Linux at all. tmux can be used on OS X, too. – slhck – 2015-04-17T11:51:49.410

    @slhck: Thanks. Too bleary-eyed; astigmatism kicked in. I had misread the tmux tag as a linux tag. – fixer1234 – 2015-04-17T16:07:07.613

    12

    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

    Posted 2010-11-10T18:40:45.620

    Reputation: 429

    8

    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)

    muneeb

    Posted 2010-11-10T18:40:45.620

    Reputation: 91

    8

    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.

    aymericbeaumet

    Posted 2010-11-10T18:40:45.620

    Reputation: 181

    1Thanks, 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 – 2018-06-05T11:02:50.543

    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)

    Update:

    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"

    phocks

    Posted 2010-11-10T18:40:45.620

    Reputation: 205

    2This one actually solves my scrolling problem in iPhone app as well. – NathaneilCapital – 2016-06-17T17:20:08.890

    The latest I tried this wasn't working any more, but this worked. Strange. set -ga terminal-overrides ',xterm*:smcup@:rmcup@' – phocks – 2016-07-05T05:30:08.617

    6

    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
    

    Chhetri

    Posted 2010-11-10T18:40:45.620

    Reputation: 61

    3Since the version 2.1 (18 October 2015) the option should be set -g mouse on – naoko – 2018-12-27T00:07:00.640

    1+1 for actually providing the full path the the configuration file. @chaiyachaiya's answer would be perfect otherwise. – John McFarlane – 2019-08-24T08:06:17.787

    4

    FWIW, on a macbook/OSX Mojave, after ctrl+[ 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 the view mode

    mithunpaul

    Posted 2010-11-10T18:40:45.620

    Reputation: 141

    -2

    • Ctrl + A - to start scrolling
    • Ctrl + C - to stop scrolling

    user656723

    Posted 2010-11-10T18:40:45.620

    Reputation: 17

    3This 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-Ais the default for GNU screen). – Anthony Geoghegan – 2016-10-26T08:50:37.767

    1Not sure if the author of this answer even understood the question. It's unhelpful and just wrong. – Vik – 2017-03-30T07:53:26.643

    2I've been looking for how to stop scrolling for so long, thanks for pointing it out! – PERR0_HUNTER – 2017-04-09T17:12:31.213