Better mouse scrolling in Tmux

Published on . Tmux OS X Workflow

With the default Tmux from homebrew, scrolling through the scrollback using the mouse is painful: It skips about 10 lines per tick of the mouse wheel, as opposed to the smooth 1 line per tick in We see how to make scrolling buttery smooth, and add a patch I made to make it even better.

Enable Smoother Mouse Scrolling in Tmux

The developer of Tmux has recently completely overhauled the mouse-interaction logic, making it a more first-class citizen in config files, akin to normal keystrokes. Also included was an update to scroll only 1 line per mouse tick, enabling a smoother scrolling experience.

If you haven’t gotten Tmux to work with the mouse yet, first take a look at Enable Mouse Support in Tmux on OS X.

These changes haven’t yet been added to a release version, so to get that update we need to install the HEAD version of Tmux:

brew remove tmux; brew install tmux --HEAD

The config has also been changed. All you need to enable mouse support is this single line:

set-option -g mouse on

There’s still one gotcha: it no longer automatically starts or stops scrolling when you scroll with your mouse in a pane like it did in the previous Tmux version. You have to first manually enter the so-called copy-mode which enables scrolling through the scrollback with prefix + [ and later manually exit copy-mode by pressing q (vi mode) or ESC (emacs mode).

Auto-Start and Stop Scrolling in Tmux

There’s a setting we can add to make auto-start work:

# Start copy mode when scrolling up
bind -n WheelUpPane copy-mode

Unfortunately there’s no such setting to auto-exit when you’re at the bottom, so I’ve created a patch to add it. Using it Tmux will automatically exit copy-mode when you scroll down further than the end, just like it did in previous versions of Tmux.

To easily install Tmux with the patch included I’ve created a custom homebrew formula, which you can install as follows:

brew remove tmux
brew install

To activate the newly added setting, update your .tmux.conf with the following:

# Enable our custom option to exit copy mode when scrolling past bottom
set-window-option -g exit-copy-past-bottom on

Let me know if this was helpful, and if you’re having any problems with it! Make sure to check out the linked files before you install them, it’s never a good idea to blindly trust a blog article with installing things on your system.

David Verhasselt

Senior full-stack engineer with 5 years of experience building web applications for clients all over the world.

Interested in working together?

Find out what I can do for you or get in touch!

Like this? Sign up to get regular updates