Take the 2-minute tour ×
Super User is a question and answer site for computer enthusiasts and power users. It's 100% free, no registration required.

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 keyboard (thanks to another question here).

Tried mouse scrolling in two versions of tmux:

  • 0.8-5hardy1 (on Ubuntu Hardy)
  • 1.3-1 (on Ubuntu Maverick)
share|improve this question
I think bukzor's answer solves your problem for tmux 1.5 and newer. –  kynan Dec 9 '11 at 13:31

5 Answers 5

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 mode-mouse on

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.

share|improve this answer
Note that you may have to reload the config file if you already have a running tmux server. blog.sanctum.geek.nz/reloading-tmux-config tmux source-file ~/.tmux.conf –  Allan Nienhuis Dec 1 '13 at 17:31

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
share|improve this answer
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 9 '11 at 13:24
@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
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

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

share|improve this answer

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.

share|improve this answer
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
Ukranian? (guessing by the i characters) –  dotancohen Apr 18 '13 at 11:17

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.

share|improve this answer
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
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 9 '11 at 13:30
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 9 '11 at 14:26
Alas, this doesn't work in iTerm –  Suan Jan 18 '12 at 0:11
I've had positive results with this in iTerm 2 –  Keith Smiley May 17 '13 at 4:14

Your Answer


By posting your answer, you agree to the privacy policy and terms of service.

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