Troubleshooting Mouse Scrolling in Tmux Sessions on Iterm2

If you’re experiencing issues with mouse scrolling in your Tmux sessions on iTerm2, you can follow these steps to troubleshoot and resolve the problem:

1. Check iTerm2 Setting: Make sure that the “Scroll wheels send arrow keys when in alternate screen mode” option is enabled in iTerm2. You can find this setting in iTerm2’s preferences. Go to iTerm2 > Preferences > Advanced, and ensure that the “Scroll wheels send arrow keys…” option is set to “Yes.”

2. Configure Tmux Plugins: To enhance mouse support in Tmux, you can use the tmux-plugins/tpm and nhdaly/tmux-better-mouse-mode plugins. These plugins enable better mouse interaction within Tmux sessions.

   Add the following lines to your ~/.tmux.conf file:

   1 2 3

   set -g @plugin 'tmux-plugins/tpm' set -g @plugin 'nhdaly/tmux-better-mouse-mode' set -g @emulate-scroll-for-no-mouse-alternate-buffer "on"

   This configuration sets up the necessary plugins and ensures that mouse scrolling works even when the alternate buffer is active.

3. Install Tmux Plugin Manager (TPM): If you haven’t already, install the Tmux Plugin Manager (TPM) by running the following command in your terminal:

   1	git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

4. Reload Tmux Configuration: After adding the plugin configuration to your ~/.tmux.conf, you need to reload your Tmux configuration. You can do this from within a Tmux session by pressing Prefix (usually Ctrl-b by default) and then typing:

   1	:source-file ~/.tmux.conf

5. Install Plugins: Inside your Tmux session, activate TPM by pressing your Tmux prefix key (e.g., Ctrl-b) followed by I (capital “i”) to install the configured plugins.

   1	<Prefix> + I

   TPM will download and install the plugins you specified in your ~/.tmux.conf file.

6. Restart Tmux: To ensure the changes take effect, you can either restart your Tmux session or create a new one.

After following these steps, mouse scrolling should work as expected in your Tmux sessions within iTerm2. If you encounter any issues, double-check your configuration and make sure you’ve correctly installed and activated the required plugins.