Scrolling on Mac with Tmux and iTerm

Question

I'm using iTerm 2.1.4 and Tmux on OS X Yosemite. I'd like to be able to scroll my iTerm windows up and down but I'm not sure what controls scrolling. Does tmux control scrolling when I use it with iTerm or does iTerm still control scrolling?

I've tried using the various keys that are supposed to scroll iTerm but all I get are "~~~~~" characters on the command line. How do I scroll with this setup?

Solution 1

Tmux scrolling is a little different than just scrolling with a mouse wheel or a trackpad.

In tmux, scrolling is accomplished by first sending 'prefix-['. You'll see a little yellow box in the upper, right-hand corner of your terminal window.

In this mode, you can use arrow keys, PageUp, PageDown, Ctrl-U, Ctrl-D, hjkl (vi-mode), or other configurable movement keys to scroll forward or back through the buffer.

There is an option in relatively recent builds of tmux that allows you to use the mouse while in scrolling mode.

add this to your .tmux.conf

set-option -g mouse on

Additionally, if memory serves, tmux is 'built into' iTerm, and thus features like multiplexing are built in as well. Is there a reason you want to use tmux in iTerm? The built-in OSX Terminal is definitely enhanced by a multiplexer like tmux, but iTerm seeks to alleviate those shortcomings by being a standalone solution.

EDIT 1: After upgrading to El Capitan, I noticed some unfamiliar behavior when using Terminal.app and tmux. This led me to an excellent article detailing options I wasn't aware of and which look to answer your question more thoroughly than I could hope to. All the options are tmux-specific, as far as I can tell, and are independent of OSX versions, so using them in Yosemite should be fine. Your scrolling question is covered here, with options like:

bind-key -t vi-copy WheelUpPane scroll-up
bind-key -t vi-copy WheelDownPane scroll-down

Many more useful options in the article linked below.

https://ryanfb.github.io/etc/2015/10/19/tmux_mouse_mode_on_el_capitan.html

Solution 2

I found following ways to deal with it (macOS Mojave):

• Enable tmux scroll mode and then press arrow up key; iTerm prompts you to set the aforementioned preference for scrolling. But in case you missed/dismissed this prompt you won't be prompted again, I think.

• Go to iTerm settings -> "Advanced" -> "Scroll wheel sends arrow keys when in alternate screen mode" -> set to "yes".

Solution 3

Met the issue these days. Env:

MacOS Big Sur 11.4

iTerm2 build 3.4.8

Tried set-option -g mouse on and only works in ctrl + b + [ mode.

Mouse scroll still shows the history message in normal mode.

Finally I found press Opt + mouse Scroll works only if there is no tmux split window.

Comments

[John Ruiz]

The link shared at the bottom of this answer is excellent but now slightly out of date. In order to accomplish your goal, you'll also need to read this: github.com/tmux/tmux/issues/754#issuecomment-297452143

[Ulysse BN]

Doesn't work for me on high sierra

[Ishan Srivastava]

works in iterm2 using tmux but messes up itself in terminal.app with things like scrolling in vim stop working and then copy paste become weirder

[Ian Smith]

This just fills my prompt with arrow key characters ^[[B^[[B^[[B^[[B^[[B^[[B^[[B^[[B^[[A^[[A^[[A^[[A^[[A

[everyonesdesign]

@IanSmith You need to enable tmux scroll mode first (i.e. press Ctrl+B and then [), and then you can scroll if the preferences are as above.