home ~ projects ~ socials

Scroll tmux one line at a time with the mouse wheel

The Config You Need

Add this to your ~/.tmux.conf file to turn on mouse scrolling that goes one line at a time:

set -g mouse on

set-option -g status-keys vi
set-window-option -g mode-keys vi

bind-key -T copy-mode-vi WheelUpPane send-keys -X scroll-up
bind-key -T copy-mode-vi WheelDownPane send-keys -X scroll-down

Notes

  • It took a surprisingly long time to find this. I found a ton of pages describing options for scrolling in tmux. They rarely mentioned the mouse. None of them showed how to do it one line at a time except the Stack Overflow answer I finally ended up on.

  • Worse, most of the sites I hit looked like this:

    Screenshot of a web page. The only content that's visible is a huge image with a generic, gray drawing of someone sitting at a computer. The title text over the image says 'How to Scroll Up and Down in Tmux - The Ultimate Guilde'. There's a banner ad below the image. That ad is partially covered by an full width ad that sticks to the bottom of the page and a video with an ad on the right side.

    The rest of the page was SEO bait talking about what tmux is and why you might want to use it. All different shapes and sizes of ads were scattered between every other paragraph.

    It made me realize that one of the appeals of AI answers showing up in search results is to avoid this type bullshit.

  • I'm using tmux version 3.5a on a mac. The Stack Overflow answer says it works from at least v2.6.

Scrolling Quality of Life

It took me forever to start using tmux. Longer until daily usage kicked in. Scrolling was a huge blocker. I'm all about hotkeys. But, it's hard to beat the mouse wheel. You know, physical hardware designed specifically for the task.

Now that I've got the scrolling config in place, it's rare that I do anything outside of tmux. It's totally worth experimenting with if you haven't tried it yet. Just know that it'll take some tweaking to get it running the way you like.

-a

-- end of line --

References

Home of the terminal multiplexer.

What appears to be the sole page on the internet that shows the config options. (I mean, I know that can't possibly be true, but it sure felt like it.)

The practice of prioritizing content aimed at show up higher in search results rather than content made for our fellow human audience.