Mouse support in Tmux is not enabled by default and must be explicitly activated through configuration settings. If mouse interactions such as clicking on panes, resizing windows, or copying text fail to work, the most common cause is that the
mouse option is set to
off or has been inadvertently disabled during a session. This article explains how to permanently enable mouse support and troubleshoot instances where it appears to stop working unexpectedly.
To resolve this issue, you need to modify your Tmux configuration file, typically located at
~/.tmux.conf. The primary command responsible for enabling mouse functionality is
set-option -g mouse on. When this setting is active, Tmux intercepts mouse events from the terminal emulator and translates them into specific actions, such as selecting a pane, scrolling through history, or entering copy mode. Without this directive, the terminal handles all mouse input directly, leaving Tmux unaware of user gestures.
Enabling Mouse Support Permanently
The most reliable way to ensure mouse support is always available is to add the configuration to your startup file. Open your
~/.tmux.conf file using a text editor like Vim or Nano. Add the following line to the end of the file:
set-option -g mouse on
After saving the file, you must either restart Tmux entirely or reload the configuration within an existing session. Reloading is faster and preserves your current sessions. To do this, enter the Tmux command prompt by pressing
Ctrl+b : (assuming the default prefix key) and type:
source-file ~/.tmux.conf
Once executed, test the functionality by clicking on different panes or attempting to scroll in a buffer. If the behavior changes immediately, the configuration was applied successfully. Note that some older versions of Tmux may require additional flags or specific terminfo entries, but modern versions (2.1+) generally support this single command effectively. For more complex configurations involving color schemes or terminfo issues, you might want to check our guide on
Troubleshooting Corrupted Data Found in Tmux 256-Color Custom Terminfo Entry, as display rendering can sometimes interfere with input handling.
Troubleshooting Intermittent Disabling
If mouse support works initially but then stops responding after a while, the issue is likely related to session state or nested Tmux environments. One common scenario occurs when you are inside a Tmux session that is itself running inside another Tmux instance. In nested environments, the outer Tmux layer may capture the mouse events before they reach the inner layer, causing the inner session to appear unresponsive to mouse clicks.
To diagnose this, check if you are in a nested session by looking at the status bar or environment variables. If you are nested, you can try forwarding mouse events from the outer session to the inner one. However, a simpler fix is often to disable mouse support in the outer Tmux if it is not needed, allowing the inner session to handle input exclusively. You can achieve this by running:
set-option -g mouse off
in the outer session. Alternatively, ensure that both layers have consistent mouse settings. Another potential culprit is the terminal emulator itself. Some terminals have their own mouse reporting protocols that conflict with Tmux. Ensure your terminal supports xterm mouse reporting, which is usually enabled by default in modern Linux distributions.
Verifying Configuration State
Sometimes, configuration files are overwritten by plugins or scripts during runtime. To verify the current state of the mouse option, use the Tmux command prompt (
Ctrl+b :) and run:
show-option -g mouse
This command will return either
on or
off. If it returns
off, it means something in your setup is actively disabling it. Check for any conditional statements in your
.tmux.conf that might toggle this setting based on host or user conditions. Additionally, inspect any plugin managers you are using, such as TPM (Tmux Plugin Manager), as some plugins may override global settings.
For users who prefer keyboard-centric workflows, understanding how to manage prefixes is crucial. If you decide to disable mouse support entirely, you might also want to adjust your prefix key bindings to improve efficiency. See our article on
Disabling the tmux Prefix Key in Your Terminal for details on customizing interaction shortcuts.
Common Pitfalls and Best Practices
One frequent mistake is placing the mouse setting inside a conditional block that only applies to specific hosts. If you move to a different machine or login via SSH, the condition may fail, resulting in disabled mouse support. Always ensure the setting is global unless there is a specific reason to limit it.
Another pitfall involves the interaction between mouse mode and copy mode. In some configurations, clicking may trigger copy mode instead of selecting a pane. This can be adjusted by fine-tuning the
mode-keys option. Setting
mode-keys vi allows for Vi-style navigation in copy mode, which can be combined with mouse selection for a hybrid workflow.
Finally, remember that Tmux updates its configuration dynamically. If you change the
.tmux.conf file while a session is active, you must reload it using
source-file. Failing to do so will result in the old settings persisting until the next server restart. Regularly auditing your configuration file helps prevent drift and ensures consistent behavior across all sessions.
Frequently Asked Questions
Why does mouse support work in new sessions but not in old ones?
Old sessions retain the configuration state from when they were created. You must reload the configuration in each active session using
source-file ~/.tmux.conf or restart the server to apply changes to existing windows and panes.
Can I enable mouse support only for specific panes?
No, the
mouse option is a global setting that applies to the entire Tmux server. It cannot be scoped to individual panes or windows. You must enable it globally or disable it globally.
Does mouse support affect performance in high-latency SSH connections?
Generally, no. Mouse events are lightweight compared to data transfer. However, if your terminal emulator is struggling with redrawing, enabling mouse mode might slightly increase CPU usage due to event processing. Monitor resource usage if you experience lag.
How do I disable mouse support temporarily without editing config files?
You can disable it instantly by opening the Tmux command prompt (
Ctrl+b :) and typing
set-option -g mouse off. This change persists only for the current session and will revert upon restart unless saved in your config.
What should I do if mouse clicks select text instead of switching panes?
This indicates that click-through is not configured correctly or that you are in copy mode. Ensure you are not in copy mode when trying to switch panes. You can exit copy mode by pressing
q or
Esc.