tmux 3.2 changed the default 'mouse' option to on — how to keep pre-3.2 behavior across mixed terminals

Question

After upgrading from tmux 3.1 to 3.2, the global mouse option now defaults to on. This means mouse-driven pane resizing, pane selection, and window switching are active even in configurations that never set the option explicitly.

The practical complication is that the effect depends on the terminal emulator's support for DECSET mouse reporting sequences (1000 for clicks, 1002 for drag, 1003 for all motion). On terminals with incomplete support — older xterm builds or Windows Console, for example — the same tmux configuration may behave inconsistently: mouse input may be ignored, or interpreted as stray keystrokes.

The goal is to restore the pre-3.2 behavior (mouse off) in a way that works reliably across a mixed fleet of terminal emulators, without breaking environments where mouse support is actually desired. Verification so far is limited to observing that tmux show-options -g mouse reports on in a fresh session on 3.2+.

Should the override be set globally in ~/.tmux.conf or scoped per session? Is there a documented way to conditionally enable mouse only when the terminal advertises proper mouse reporting? Does setting mouse off have any side effects on copy-mode selection behavior that should be accounted for?

Tasadduq Burney · Answer

After tmux 3.2 (June 2021) changed the global default of the mouse option from off to on, new sessions start with mouse-driven pane selection, resizing, and window switching active by default. Restoring the pre-3.2 behavior is straightforward if you want mouse disabled across your fleet.

Confirmed fact
Adding set -g mouse off to ~/.tmux.conf and reloading with tmux source-file ~/.tmux.conf forces the default to off for all new sessions. Verification: run tmux show-options -g mouse; it should report off.

Likely explanation & boundary conditions
The mouse option is session-scoped. set -g mouse off sets the default for new sessions only; existing sessions retain their current value until explicitly changed. tmux has no built-in mechanism to conditionally enable mouse based on terminal DECSET capability (1000/1002/1003). Terminal capability detection must be done externally, such as shell logic in ~/.tmux.conf inspecting $TERM, $TERM_PROGRAM, or using infocmp/tic to query terminfo. On terminals with incomplete mouse reporting — older xterm builds, Windows Console, or certain terminal emulators — mouse input may be ignored or interpreted as stray keystrokes when left on.

Steps needed for this case

Add set -g mouse off to ~/.tmux.conf.
  Reload the configuration: tmux source-file ~/.tmux.conf.
  Start a new tmux session and verify: tmux show-options -g mouse should report off.
  To re-enable mouse in a specific session later, run tmux set mouse on inside that session; the change does not persist across restarts unless added to a session-specific config.

If you need mouse support active in particular sessions across your mixed terminal fleet, the safest approach is to add a conditional snippet to ~/.tmux.conf that checks the terminal identifier. However, because $TERM often does not distinguish capable from incapable terminals, this approach is fragile. If per-session conditional enablement is a requirement, please run tmux -V and echo $TERM in a fresh session and share the output; a tailored snippet can be generated once the terminal type is known.

tmux 3.2 changed the default 'mouse' option to on — how to keep pre-3.2 behavior across mixed terminals

1 answer

Confirmed fact

Likely explanation & boundary conditions

Steps needed for this case

Your perspective belongs here.

0 question comments