330

To allow scrolling a tmux pane with a mouse, I put the following in my ~/.tmux.conf file:

set -g mouse-mode on

However, nothing changes. When I scroll, it still scrolls outside of tmux. Why is this?

1
  • 2
    mode-mouse in the old version
    – hyiltiz
    Feb 11, 2020 at 21:09

11 Answers 11

722

So this option has been renamed in version 2.1 (18 October 2015)

From the changelog:

 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

So this is what I'm using now in my .tmux.conf file

set -g mouse on
8
  • @Sukima - The changelog can be found here.
    – TxH
    Dec 25, 2015 at 19:27
  • I'm confused, as I have version 2.1 installed on two different systems, both Ubuntu 16.04 (one hasn't been upgraded in a long time.) However, though both report version 2.1 when running tmux -V, I have to use the mouse option on one system and the old names on the other. Anyone know why this could be the case?
    – Andrakis
    Jul 23, 2017 at 12:49
  • 5
    While this is working for Mac, it with set -g mouse on, it will break the ability to select text in Mac's terminal. I have to specifically do set -g mouse off to select text
    – Wins
    Apr 18, 2018 at 17:36
  • 4
    @Wins press shift before selecting or pasting
    – mdekkers
    May 25, 2018 at 5:39
  • 1
    @Wins try alt, that's what I use for iTerm2 Feb 19, 2019 at 20:50
84

As @Graham42 noted, mouse option has changed in version 2.1. Scrolling now requires for you to enter copy mode first. To enable scrolling almost identical to how it was before 2.1 add following to your .tmux.conf.

set-option -g mouse on

# make scrolling with wheels work
bind -n WheelUpPane if-shell -F -t = "#{mouse_any_flag}" "send-keys -M" "if -Ft= '#{pane_in_mode}' 'send-keys -M' 'select-pane -t=; copy-mode -e; send-keys -M'"
bind -n WheelDownPane select-pane -t= \; send-keys -M

This will enable scrolling on hover over a pane and you will be able to scroll that pane line by line.

Source: https://groups.google.com/d/msg/tmux-users/TRwPgEOVqho/Ck_oth_SDgAJ

2
  • 3
    This seems to work, however I can't select text in panes anymore. Anyone else also having this issue?
    – will.fiset
    Apr 16, 2018 at 20:48
  • 1
    @will.fiset: yes, this is expected as mentioned in the FAQs. hold the shift-key while you try to mark text, this should work in most terminals. Aug 11, 2020 at 14:51
80

Just a quick heads-up to anyone else who is losing their mind right now:

https://github.com/tmux/tmux/blob/310f0a960ca64fa3809545badc629c0c166c6cd2/CHANGES#L12

So that's just

:setw -g mouse
2
  • 4
    Or if you want it always on, simply add set -g mouse in ~/.tmux.conf. Though note that this will make copying/pasting text into the terminal via the mouse more difficult (I'm sure there's a way - I just haven't looked it up myself). May 17, 2018 at 17:43
  • 2
    @J.M.Janzen Many terminals keep mouse events for themselves if you hold Shift while clicking. The mouse event won't be passed to tmux (or vim, for that matter) and text will be selected natively by the terminal.
    – piojo
    Dec 14, 2020 at 3:43
43

this should work:

setw -g mode-mouse on

then resource then config file

tmux source-file ~/.tmux.conf

or kill the server

2
  • I used set -g mouse on and the source-file command you gave, worked perfectly. Mar 25, 2018 at 10:15
  • 1
    .tmux.conf:1: invalid option: mode-mouse
    – alper
    Aug 27, 2020 at 21:09
28

Paste here in ~/.tmux.conf

set -g mouse on

and run on terminal

tmux source-file ~/.tmux.conf
1
  • Thanks, worked for byobu --version byobu version 5.73 tmux 2.5 while the suggestions above didn't.
    – Thomas
    Feb 1, 2019 at 13:22
19

This line:

set -g mouse-mode on

in your ~/.tmux.conf file won't work.

For one thing, the proper setting is mode-mouse, not mouse-mode.

Second, it only works on older versions of tmux (pre-version 2; you can run tmux -V to see what version you have, but you can also run man tmux to see if mode-mouse is a supported option).

And third, technically man tmux says to use the mode-mouse option with setw (set-window-option) and not with set (set-option), although I've seen it work with set (as well as setw).


These lines should work:

If your version of tmux is recent enough (that is, if tmux -V shows version 2 or newer), you can put this line in your ~/.tmux.conf file:

set-option -g mouse on

But if you use an older version of tmux, put these lines in your ~/.tmux.conf file:

set-window-option -g mode-mouse on

set-option -g mouse-resize-pane on
set-option -g mouse-select-pane on
set-option -g mouse-select-window on

Again, if you're not absolutely sure which line(s) to put in your ~/.tmux.conf file, run man tmux and search for mouse-mode, mouse-resize-pane, mouse-select-pane, and/or mouse-select-window. If you find them, then use those options (the ones for the older version of tmux).

Putting these lines in will allow you to use the mouse scroll wheel, it will allow you click on various panes to activate them, and it will allow you to resize panes just by clicking-and-dragging on their splitter separator.

You can also copy-and-paste using your mouse. However, you may notice that copying-and-pasting with your mouse may not work like it normally does on your console. To work around this, I've noticed that holding down the SHIFT key while using your mouse's copy/paste abilities makes them work normally again. (On MacOS, fn seems to work for me better than SHIFT.) Or you can learn tmux's approach to copy-and-pasting (which I do recommend).


A note on using tmux's native ability to copy/select/paste:

Personally, I feel that the vi keys make more sense to me than the default emacs keys (for example, it feels more natural to exit selection mode with vi mode's ENTER than with emacs mode's CTRL+w or ALT+w), so I have this in my ~/.tmux.conf file:

# For vi-like keys in copy/paste/selection mode:
set-window-option -g mode-keys vi

However, I've noticed that on older versions on tmux, this line won't work, unless I've also included the line:

set-window-option -g mode-mouse on

Good to know: Occasionally, when you're using the mouse's scroll wheel, you'll discover that your pane/screen appears to be frozen or locked up (it won't respond to keyboard input), and it's not clear what to do to unlock it.

It's not locked up. You're likely in tmux's selection mode. To get out of it, try one of these:

  • Hit ENTER. (Will likely work in vi mode.)
  • Hit ALT+w. (Will likely work in emacs mode.)
  • Hit CTRL+w. (Will likely work in emacs mode.)
  • Hit META+w. (Will likely work in emacs mode.)
  • Hit Esc. (Will likely work in emacs mode.)
  • Hit q. (Will likely work in vi mode, and may work in emacs mode as well.)

Ultimately, you can try hitting:

CTRL+w     ENTER

or:

Esc     q

Chances are, that will put you back in the normal mode where your keyboard is responsive again.


Using the mouse with vim:

I've discovered that putting this line in my ~/.vimrc file:

:set mouse=a

seems to work well with tmux, better than this line:

:set mouse=r

I can't really explain the difference; if you're a vim user, try them out and see which setting works best for you.


If you need to test out these tmux options, you may find yourself editing your ~/.tmux.conf file, exiting tmux, and then restarting tmux. This can become a tedious process, so if you want some work-arounds, here are some options:

Option1: After editing (and saving) your ~/.tmux.conf file, run this command (while in tmux):

CTRL+B :source-file ~/.tmux.conf ENTER

This will immediately apply the new settings in your ~/.tmux.conf file into your current tmux session, without the need to restart tmux.

Option 2: If you're in a tmux session, you can turn on/off options temporarily just for that session by running commands like these at the Unix shell prompt:

tmux set-option -g mouse on

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

Option 3: You can also temporarily turn on/off options in a tmux session with:

CTRL+B :set-option -g mouse on ENTER

CTRL+B :set-window-option -g mode-keys vi ENTER


Good luck, and have fun using tmux !

17

As @Graham42 said, from version 2.1 mouse options has been renamed but you can use the mouse with any version of tmux adding this to your ~/.tmux.conf:

Bash shells:

is_pre_2_1="[[ $(tmux -V | cut -d' ' -f2) < 2.1 ]] && echo true || echo false"
if-shell "$is_pre_2_1" "setw -g mode-mouse on; set -g mouse-resize-pane on;\
      set -g mouse-select-pane on; set -g mouse-select-window on" "set -g mouse on"

Sh (Bourne shell) shells:

is_pre_2_1="tmux -V | cut -d' ' -f2 | awk '{print ($0 < 2.1) ? "true" : "false"}'"
if-shell "$is_pre_2_1" "setw -g mode-mouse on; set -g mouse-resize-pane on;\
      set -g mouse-select-pane on; set -g mouse-select-window on" "set -g mouse on"

Hope this helps

10
  • 1
    the idea behind this answer is pure genius! ...and could also help for style-options resp. fg-, bg- and attr-abolition in tmux 2.9. but it does not work because at least my shell refuses to compare floating-point numbers... and if your localization uses something else than . as a floating-point, you must also work around this issue. Nov 7, 2019 at 9:17
  • @DJCrashdummy What's the output of tmux -V | cut -d ' ' -f2 in your shell? Nov 7, 2019 at 9:58
  • @DJCrashdummy I've improved my answer. Test the new version! Nov 7, 2019 at 10:20
  • 2
    Note: on ubuntu 19.10, the version is tmux 2.9a. So I used tmux -V | sed -E 's/tmux ([0-9.]*).*$/\\1/;' to parse it more robustly.
    – autra
    Apr 21, 2020 at 19:33
  • 2
    Note: that at least for me on Ubuntu 18.04, even if /bin/sh is Bash, I need the Sh syntax, probably because Bash enters POSIX mode
    – philb
    Jun 16, 2020 at 15:52
13

You can still using the devil logic of setting options depending on your current Tmux version: see my previous answer.

But since Tmux v1.7, set-option adds "-q" to silence errors and not print out anything (see changelog). I recommend to use this feature, it's more readable and easily expandable.

Add this to your ~/.tmux.conf:

# from v2.1
set -gq mouse on
# before v2.1
set -gq mode-mouse on
set -gq mouse-resize-pane on
set -gq mouse-select-pane on
set -gq mouse-select-window on

Restar tmux or source-file your new .tmux.conf


Side note: I'm open to remove my old answer if people prefer this one

0
3

Try this. It works on my computer.

set -g mouse on
0

For anyone actually losing it because they already have set -g mouse on, check your terminal settings to see if "Enable mouse reporting" is on.

-2

Ctrl + B and then set mouse. -g is not needed anymore.

2
  • 1
    Mouse doesn't do anything after ctrl b Sep 20, 2021 at 2:25
  • push <kbd>Ctrl</kbd> + <kbd>B</kbd> and then :set mouse Jan 5, 2022 at 11:48

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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