1789

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?

5
  • 8
    What overhead are you concerned with? copy-mode is the way to view history (and optionally copy stuff out of it). Nov 11, 2010 at 5:48
  • 3
    for me you can press f7 for scroll mode and q to quit Jul 25, 2014 at 14:56
  • 15
    set -g mode-mouse on per @chaiyachaiya's answer was the winner for me
    – Peter Berg
    Jul 21, 2016 at 19:36
  • 12
    Just run: echo "set -g mouse on" >> ~/.tmux.conf and you'll be able to scroll.
    – Noam Manos
    Mar 10, 2020 at 8:28

14 Answers 14

2146

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.

23
  • 20
    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). Nov 11, 2010 at 5:55
  • 4
    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, 2010 at 17:11
  • 49
    @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> Nov 11, 2010 at 18:43
  • 6
    on macbook, the fn+up goes straight to terminal app and never hits tmux
    – Tyler
    Apr 11, 2011 at 17:57
  • 16
    On a macbook if you're in scroll mode you can use fn+Shift+LeftArrow to scroll up a page. May 18, 2013 at 17:51
457

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.

15
  • 7
    When 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
    Aug 1, 2013 at 15:38
  • 41
    Future tmux mouse users: To save you having to scroll to the bottom again before typing, you can hit q to exit scroll mode. Jan 7, 2014 at 5:11
  • 23
    Mouse scrolling works fine with this, but unfortunately I cannot use the mouse to select text anymore. Using Tilda and tmux. Mar 17, 2015 at 3:40
  • 41
    Important note: This setting breaks highlighting and copying text. Use shift+click to maintain this functionality.
    – Shadoninja
    May 4, 2016 at 22:50
  • 3
    1) we can no longer select text using clicks 2) we can't scroll into vim
    – pltrdy
    Nov 27, 2017 at 15:54
175

From my .tmux.conf:

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

This enables native xterm scrolling.

16
  • 36
    Can you explain what this does exactly?
    – Ivo
    Oct 31, 2011 at 6:25
  • 16
    I don't know what it does, but it is pure genius. Finally, tmux scrolling works, yay!
    – oneself
    Nov 28, 2011 at 21:26
  • 7
    This doesn't work for me on OS X...
    – Nick
    Apr 17, 2012 at 13:56
  • 17
    Solution: gist.github.com/1297707
    – Nick
    Apr 17, 2012 at 15:25
  • 9
    Check this out if you're confused about togdon's answer: superuser.com/questions/310251/… IMO, if you have only a single pane, this solution works better than the accepted answer.
    – thameera
    Apr 16, 2013 at 7:48
81

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

8
  • 2
    How is this not the accepted answer?
    – Marcel
    Dec 21, 2016 at 20:28
  • 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, 2017 at 18:05
  • 3
    could you elaborate on how this works?
    – oligofren
    Jul 19, 2017 at 7: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 2, 2018 at 14:13
  • 3
    @chefarov - per a comment on another answer, you can do this via Shift+click when you have mouse mode on. Mar 27, 2019 at 13:23
22

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

4
  • @fixer1234 The question does not mention Linux at all. tmux can be used on OS X, too.
    – slhck
    Apr 17, 2015 at 11:51
  • @slhck: Thanks. Too bleary-eyed; astigmatism kicked in. I had misread the tmux tag as a linux tag.
    – fixer1234
    Apr 17, 2015 at 16:07
  • Simplest + no setup required solution!
    – b.ben
    Dec 26, 2021 at 2:33
  • This is what I was looking for while using the macOS Terminal. Mar 8 at 21:11
17

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
11

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.

1
  • 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 5, 2018 at 11:02
10

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)

0
10

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
4
  • 4
    Since the version 2.1 (18 October 2015) the option should be set -g mouse on
    – naoko
    Dec 27, 2018 at 0:07
  • 1
    +1 for actually providing the full path the the configuration file. @chaiyachaiya's answer would be perfect otherwise. Aug 24, 2019 at 8:06
  • +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, 2021 at 18:22
  • Very helpful. The sourcing of the config file was missing in other answers. Thanks!
    – normanius
    May 31 at 8:13
10

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"

2
  • 2
    This one actually solves my scrolling problem in iPhone app as well. Jun 17, 2016 at 17:20
  • The latest I tried this wasn't working any more, but this worked. Strange. set -ga terminal-overrides ',xterm*:smcup@:rmcup@'
    – phocks
    Jul 5, 2016 at 5:30
9

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
1
  • Thanks, this works!
    – Zion Perez
    Oct 2, 2021 at 2:21
0

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

0

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

after that its easy to navigate with vim config

-3
  • Ctrl + A - to start scrolling
  • Ctrl + C - to stop scrolling
3
  • 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-Ais the default for GNU screen). Oct 26, 2016 at 8:50
  • 3
    Not sure if the author of this answer even understood the question. It's unhelpful and just wrong.
    – Vik
    Mar 30, 2017 at 7:53
  • 2
    I've been looking for how to stop scrolling for so long, thanks for pointing it out! Apr 9, 2017 at 17:12

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.