How to enable mouse support in tmux

Enabling mouse support in tmux makes it possible to click a window in the status line, move focus between panes, resize pane borders, and scroll through pane history without leaving the multiplexer. It is useful when a session has several panes open or when occasional pointer control is faster than reaching for another key binding.

Current tmux releases use one mouse option for mouse handling. The tmux server reads its config from ~/.tmux.conf or an XDG config path when the server starts, and the source-file command reloads later changes into an already running server so the new setting applies to current sessions.

Mouse support changes how scroll and selection events are divided between tmux, the terminal emulator, and programs inside a pane. Full-screen tools such as vim, less, or man may keep mouse events for themselves, and terminal-emulator scrollback or text selection may behave differently until mouse mode is turned off again.

1. Open the tmux config file in a text editor.

   $ vi ~/.tmux.conf

   tmux also reads $XDG_CONFIG_HOME/tmux/tmux.conf or ~/.config/tmux/tmux.conf when those paths are used instead of ~/.tmux.conf.

2. Add the mouse setting to the config file.

   set -g mouse on

   Current tmux releases use this single option instead of older settings such as mode-mouse, mouse-select-pane, or mouse-resize-pane.

3. Save the file and return to the shell prompt.
4. Reload the active tmux server so the updated setting is applied to current sessions.

   $ tmux source-file ~/.tmux.conf

   If no tmux server is running yet, start a new session instead because the config file is read when the server starts.

   Related: How to reload the tmux config

5. Confirm that the current tmux server now reports mouse support as enabled.

   $ tmux show-options -g mouse
   mouse on

   The same check works after starting a new session when the config was not reloaded into an existing server.

6. Test the new behavior by clicking another pane, dragging a pane border, or using the mouse wheel over pane history.

   The default mouse bindings let tmux select and resize panes, copy text, and change windows from the status line when mouse is on.

   Applications running inside a pane can enable their own mouse handling, so wheel and drag events may go to the program instead of tmux until that program exits or its mouse mode is disabled.

   Related: How to use copy mode in tmux