386

Mouse scrolling doesn't work in tmux the way it works when I run shell without tmux (in Gnome Terminal). It seems tmux sends mouse scroll events as if I pressed Up/Down keys. But I want it to scroll though the shell output history. Is there a way to make tmux work like this?

Note: I know how to scroll with the keyboard (thanks to another question here).

I tried mouse scrolling in two versions of tmux:

Community
  • 1
user31494
  • 3,973

14 Answers14

397

To scroll within history of the output You would use ^b + [ You can then use M+V to page up and ^V to page down. I don't know if You can use the real PgUp and PgDown though. My terminal does not send these keys to the tmux. Instead it scrolls itself and not the tmux history.

To exit the copy mode, press ESC

To use your mouse in this mode (called copy mode) press ^b + : and enter following:

setw -g mouse on

Note: In tmux < 2.1, the option was named mode-mouse, and not mouse

Now when You change to the copy mode you can use your mouse to scroll through it. You can put this command in your ~/.tmux.conf if You want so it loads every time You run tmux.

Update: As of tmux 1.5 this option makes using the scroll wheel automatically switch to copy mode and scroll back the tmux scrollback buffer. It is not necessary to first hit Ctrl-B + [ any more. Scrolling back down to the prompt also ends copy mode automatically.

Community
  • 1
Pavlo
  • 4,071
154

There are some changes for Tmux 2.1

  • Mouse-mode has been rewritten. There's now no longer options for:

    • mouse-resize-pane
    • mouse-select-pane
    • mouse-select-window
    • mode-mouse

    Instead there is just one option: 'mouse' which turns on mouse support entirely.

That would be 

set -g mouse on
# to enable mouse scroll, see https://github.com/tmux/tmux/issues/145#issuecomment-150736967
bind -n WheelUpPane if-shell -F -t = "#{mouse_any_flag}" "send-keys -M" "if -Ft= '#{pane_in_mode}' 'send-keys -M' 'copy-mode -e'"
Olivier Lalonde
  • 10,307
DannyRe
  • 1,651
  • 8
    Thanks, now selecting panes, etc work, but scrolling doesn't. In order to make scrolling work again, use this: https://github.com/NHDaly/tmux-scroll-copy-mode – Mahdi Oct 20 '15 at 20:15
  • 2
    awesome - this even works on cygwin - tmux on WINDOWS 7 – GWD Jan 21 '16 at 15:52
  • @Mahdi This seems to not work on osx. Any hints? – rdbisme Feb 11 '16 at 08:39
  • @SolidSnake: I don't remember facing any issues using that plugin. It worked smoothly, I enabled mouse mode and then installed it. You should reload your tmux config using tmux source-file ~/.tmux.conf – Mahdi Feb 11 '16 at 20:01
  • 4
    bind doesn't seem to be necessary anymore on tmux 2.3 – Theron Luhn Dec 05 '16 at 18:49
  • 11
    +1 for set -g mouse on . Previous comment is correct. The bind is no longer needed. – Dakusan Feb 12 '18 at 19:19
  • this works but causes the lessoutput of git diff to not scroll with the mouse wheel (vim has no issue) – crackpotHouseplant Aug 30 '20 at 00:46
  • -1 for set -g mouse on - disables ability to copy-paste with the mouse, at least select/right click no longer works – Dmitry z Nov 28 '20 at 06:26
  • it said to me ambiguous option mouse. How do I fix this? I am trying to set mouse on from a remote hpc... – Charlie Parker May 06 '22 at 20:59
75

The current version of tmux (1.5) lets you simply set the mode-mouse option on, and allows you to scroll with the mouse wheel.

         mode-mouse [on | off]
                 Mouse state in modes.  If on, the mouse may be used to
                 enter copy mode and copy a selection by dragging, to
                 enter copy mode and scroll with the mouse wheel, or to
                 select an option in choice mode.

In my .tmux.conf:

set-window-option -g mode-mouse on

update - as of tmux 2.1 this option has been renamed to simply mouse

jsbueno
  • 863
bukzor
  • 2,102
  • 2
  • 16
  • 21
  • That is the behaviour you really want! Mouse scroll enabling copy mode, not just scrolling the shell alternate buffer. That was finally the incentive to switch from screen to tmux for me. Is there an option to get the same behaviour also with Shift+PgUp? – kynan Dec 09 '11 at 13:24
  • 1
    @kynan: I personally just press C-A PgUp to do that. You can bind the page-up key directly with tmux bind-key -n PPage copy-mode -u. The similar thign should work for shift+pageup if you un-bind it from your local terminal. – bukzor Dec 12 '12 at 20:04
  • 1
    This results in an odd behaviour where, when I scroll back to the command line, I get an extra character inserted into the CLI, which usually results in my first command being malformed. It's pretty annoying. – Chris R Dec 27 '12 at 17:01
  • Note that, however this works fine for triggering the scroll with the mouse, it causes odd behavior when selecting text to be pasted with middle-click. I ended up preffering C-b pg-up/down (the default) since the tradeoff was not acceptable. – h7r May 14 '15 at 19:18
  • @ChrisR I get this quite a bit too and it isn't quite consistent. Is it a [M [M#[M [M#[M [M#[M [M#[M type of string? – Elijah Lynn Jan 08 '16 at 00:34
  • Yeah this works for tmux 1.8 on CentOS 7.9. tmux version on CentOS 7 are bit old. – Benyamin Limanto Jul 31 '21 at 04:17
  • it said to me ambiguous option mouse. How do I fix this? I am trying to set mouse on from a remote hpc... – Charlie Parker May 06 '22 at 20:59
  • @CharlieParker You're using the older version of tmux, sounds like. You can upgrade or use the older version of John L. Jegutanis' answer – bukzor Aug 17 '22 at 18:17
71

Update:

Like others mentioned, in the newer tmux versions, you need to simply put the following in your .tmux.conf

setw -g mouse on

Previous recommendation for older tmux versions:

Try this in your .tmux.conf

# Make mouse useful in copy mode
setw -g mode-mouse on

Allow mouse to select which pane to use


set -g mouse-select-pane on


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"


Scroll History


set -g history-limit 30000


Set ability to capture on start and restore on exit window data when running an application


setw -g alternate-screen on


Lower escape timing from 500ms to 50ms for quicker response to scroll-buffer access.


set -s escape-time 50

Taken from http://brainscraps.wikia.com/wiki/Extreme_Multitasking_with_tmux_and_PuTTY

John L. Jegutanis
  • 819
  • +1 for escape-time setting – Dakusan Feb 12 '18 at 19:22
  • 2
    For anyone else wondering, the .tmux.conf file is placed in your home directory. – user2647513 Sep 03 '19 at 14:56
  • 3
    Replace mouse settings with just set -g mouse on – Shital Shah Dec 11 '19 at 10:25
  • 1
    This was working great for me on Ubuntu 18.04LTS until May 2020, then started giving me warnings and all sorts of things not working. I guess something upgraded itself?? It seems better if I remove the mouse options, replace with set -g mouse on (q.v. https://stackoverflow.com/a/33336609/303056 ) and remove terminal-overrides – Leopd May 26 '20 at 17:25
16

Someone (from a source I lost) suggested adding the following to ~.tmux.conf:

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

I have no idea how it works or what it does, but this now allows me to scroll with the mouse wheel inside a tmux session without having to enter tmux's copy mode; I just scroll the wheel and BAM! it works. Note that I'm using terminal.app, but I remember the OP gave the answer specifically for use with gnome-terminal.

tshepang
  • 3,311
Jed Daniels
  • 1,214
  • 2
    Jed, thank you! Your advice works in gnome-terminal too. I will try to use this setup for some time. But it has a disadvantage: mouse scrolling now doesn't work as expected in less. If I load less inside tmux, mouse scrolling doesn't scroll the file opened in less. It scrolls the whole terminal. Strangely, vim behaves as expected inside tmux with your setup. – user31494 Jul 14 '11 at 18:08
  • 2
    Note that as of tmux 1.5 this is superseded by the setw -g mode-mouse on option, which does copy mode scrollback using the mouse wheel. – kynan Dec 09 '11 at 13:30
  • 4
    The explanation is that this option disables the scroll lock on the terminal's alternate screen, which is desirable in most cases since applications requesting the alternate screen buffer (vi, less, tmux etc.) provide their own scrolling capabilities. Overriding this lock in tmux allows scrolling the terminal's alternate screen buffer which doesn't give the desired result in all but a few cases. See this answer for a quote from man xterm explaining alternate screen. – kynan Dec 09 '11 at 14:26
  • Alas, this doesn't work in iTerm – Suan Jan 18 '12 at 00:11
  • I've had positive results with this in iTerm 2 – Keith Smiley May 17 '13 at 04:14
  • This worked for me as well using Terminal.app. – fiorix Mar 18 '14 at 05:45
  • it mess up the screen if you have multiple panels... – David S. Dec 02 '14 at 01:20
  • Not working with tmux on OS X (Yosemite), scrolls the whole window. – Ain Mar 11 '15 at 09:46
  • @Ain: I think yosemite changed the default, but you can switch it back under terminal preferences->Profiles->Keyboard->"Scroll Alternate Screen". Or you can hold the shift key while scrolling instead. – Jed Daniels Mar 12 '15 at 02:27
  • It does not work in my case (bash inside of Visual Studio Code). I still need to enter copy mode to scroll output in tmux. – Antonio Sesto May 10 '22 at 07:28
14

If you are already in a tmux session you can run the command

set mouse on

Reminder: to run commands, use your prefix then :.

Robert
  • 269
7

tmux 2.1 introduces new mouse binds.

I wrote these binds just now today. It seamlessly binds mouse wheel to arrows when not in Vim, because Vim is capable of interpreting the raw mouse wheel codes (for purposes such as choosing which Vim window to scroll for you depending on which one your mouse is over).

This means we can finally use the mouse only to view multiple man pages and whatever else accepts arrow keys. You may extend and chain the if logic as necessary to implement more logic for your applications.

bind -n WheelUpPane if "[[ #{pane_current_command} =~ vim ]]" "select-pane -t = ; send-keys -M" "select-pane -t = ; send-keys Up"
bind -n WheelDownPane if "[[ #{pane_current_command} =~ vim ]]" "select-pane -t = ; send-keys -M" "select-pane -t = ; send-keys Down"

With this new wheel binding capability it is possible to script the mouse wheel to do any context sensitive behavior that you like.

Steven Lu
  • 3,668
  • I'm now just sort of toying with the idea of making mousewheel on pane border do something interesting. Probably what I'll do is not map wheel on border but map it to cycle the tmux windows when done over the statusline. – Steven Lu Dec 15 '15 at 23:53
  • 1
    What's the link to your Github? I'd like to keep abreast of your efforts! Another feature I am looking for is to have double-click copy the word to the X clipboard, like it does outside of Tmux. – joeytwiddle Mar 30 '16 at 03:11
  • 1
    @joeytwiddle I highly recommend https://github.com/NHDaly/tmux-better-mouse-mode, see my other answer – Steven Lu Jan 02 '18 at 23:54
4

None of the other answers worked entirely for me in themselves. I had to enable the mouse option, using set -g mouse on and then used Shift + Mouse Wheel to scroll through the terminal.

Zoso
  • 183
  • 1
  • 10
3

The following worked fine for me even for a current session which I detached.

tmux set-option mouse on

After that attach to your session again.

tmux attach -t 0
Matthis Kohli
  • 131
  • 3
3

Gnome-terminal does some neat trickery translating mouse scroll events to Up and Down arrow keys in conditions of restricted "usual" scrolling. For example, when you view some text using less (this happens in particular when you're reading a man), you can scroll the content using j, k, and arrow keys. But also, with gnome-terminal, you can do that with mouse scrolling, thanks to the mentioned trick.

So I guess tmux does some "capturing" of the terminal just like less - and the same mechanism in gnome-terminal kicks in: mouse scrolling translates into Up/Down arrow key presses.

You can turn this feature off in profile settings and get the regular scrolling in any circumstances. Just unmark the last checkbox in the "scrolling" tab: the checkbox.

ulidtko
  • 2,946
  • Thank you for explanation, uldtko! But it doesn't help with the mouse scrolling problem. Yes, with the option turned off, gnome-terminal stops sending triple ^[[A and ^[[B on mouse-scroll. It's nicer in tmux (no ugly ^[[A^[[A^[[A in some programs, no ugly command-history-scrolling), but now less stops scrolling on mouse-scroll. – user31494 Dec 27 '10 at 14:48
  • 3
    Ukranian? (guessing by the i characters) – dotancohen Apr 18 '13 at 11:17
1

https://github.com/NHDaly/tmux-better-mouse-mode

Configurable and feature-rich implementation of mouse control for newer tmuxes. highly recommended.

You likely want to use

set -g @emulate-scroll-for-no-mouse-alternate-buffer "on"

with it also.

Steven Lu
  • 3,668
0

I'm using Warp, and I solved this issue with

Warp Settings > Features > Enable Mouse Reporting.

tanaydin
  • 101
  • Your answer could be improved with additional supporting information. Please [edit] to add further details, such as citations or documentation, so that others can confirm that your answer is correct. You can find more information on how to write good answers in the help center. – Community Mar 18 '24 at 11:36
0

With mouse mode on and mapping the mouse wheel with Up/Down keys works pretty nice. Note: Reverse bindings if you don't like natural scroll.

set -g mouse on
bind -n WheelUpPane if -t = "test $(echo #{pane_current_command} |grep -e 'vim' -e 'man' -e 'less')" "select-pane -t = ; send-keys Up Up Up"  "if-shell -F -t = '#{?mouse_any_flag,1,#{pane_in_mode}}' 'send-keys -M' 'select-pane -t = ; copy-mode -e; send-keys -M'"
bind -n WheelDownPane if -t = "test $(echo #{pane_current_command} |grep -e 'vim' -e 'man' -e 'less')" "select-pane -t = ; send-keys Down Down Down"  "if-shell -F -t = '#{?mouse_any_flag,1,#{pane_in_mode}}' 'send-keys -M' 'select-pane -t = ; copy-mode -e; send-keys -M'"
Liv
  • 1
  • kudos to @stealz for the solution. I just adapted a little - see it as a report cause his had a negative vote, and I could not vote yet. – Liv Mar 23 '24 at 08:46
-1

You can combine the binding ideas from the other answers to get a pretty satisfying scrolling behavior: works in vim changes to copy mode automatically in terminal and exits it when you reach the bottom still allows you to use your mousewheel in man, less and journalctl.

My code:

bind -n WheelUpPane if -t = "test $(echo #{pane_current_command} |grep -e 'man' -e 'less' -e 'journalctl')" "select-pane -t = ; send-keys Up Up Up Up"  "if-shell -F -t = '#{?mouse_any_flag,1,#{pane_in_mode}}' 'send-keys -M' 'select-pane -t = ; copy-mode -e; send-keys -M'"
bind -n WheelDownPane if -t = "test $(echo #{pane_current_command} |grep -e 'man' -e 'less' -e 'journalctl')" "select-pane -t = ; send-keys Down Down Down Down"  "if-shell -F -t = '#{?mouse_any_flag,1,#{pane_in_mode}}' 'send-keys -M' 'select-pane -t = ; copy-mode -e; send-keys -M'"

you can add other commands that require arrow keys for scrolling in the grep -e 'man' part

i added the send-keys multiple times, so one tick on the mousewheel will scroll 4 lines at a time

stealz
  • 1