You can actually ditch your mouse entirely when using tmux, and it’s surprisingly powerful once you enable it.
Here’s how it looks when it’s working:
+-----------------------------------------------------------------+
| 0:bash * |
| |
| user@host:~$ echo "Hello, tmux mouse!" |
| Hello, tmux mouse! |
| user@host:~$ |
| |
+-----------------------------------------------------------------+
| 1:bash |
| |
| user@host:~$ top |
| |
| |
+-----------------------------------------------------------------+
Imagine you’re in a top session in pane 1 and want to quickly switch to your bash prompt in pane 0. With mouse support enabled, you just click on pane 0. Want to resize pane 1 to be taller? Click and drag its bottom border. Need to scroll back through the output of a long command? Just spin your mouse wheel. It feels like a GUI terminal, but it’s all within your text-based tmux session.
The magic happens through a few key tmux options. The primary one is mouse on. This is the master switch. When it’s set to on, tmux starts listening for mouse events like clicks, drags, and scrolls.
Here’s the minimal configuration you need in your ~/.tmux.conf to get started:
set -g mouse on
After adding this line, you need to tell your running tmux session to reload its configuration. You can do this by pressing your tmux prefix key (usually Ctrl+b) followed by a colon (:), which brings up the tmux command prompt, and then typing source-file ~/.tmux.conf and pressing Enter. Alternatively, you can just kill your tmux server (tmux kill-server) and start a new session.
Once mouse on is active, tmux interprets mouse clicks in different ways depending on the context. A click on a pane border will allow you to resize that pane. A click within a pane will switch focus to that pane. You can also select text by clicking and dragging, which will copy it to tmux’s buffer.
Scrolling is also a game-changer. If you have more output in a pane than can fit on the screen, spinning your mouse wheel will scroll up and down through that pane’s history. This is incredibly useful for reviewing logs or long command outputs without needing to manually enter copy mode.
Beyond the basic mouse on, there are a few other granular options that refine this experience:
mouse-resize-pane on: This is implicitly enabled bymouse on, but you can explicitly set it. It allows you to resize panes by clicking and dragging their borders.mouse-select-pane on: Also part ofmouse on. This lets you switch focus between panes by clicking on them.mouse-select-text on: Again, part ofmouse on. This enables text selection and copying to the tmux buffer via mouse drag. You can then paste this buffer content using your prefix key followed by].mouse-wheel on: This is crucial for scrolling. It enables mouse wheel support for scrolling within panes. Without this, your mouse wheel might just scroll your terminal emulator’s scrollback history instead of tmux’s pane history.
So, a more comprehensive configuration might look like this:
set -g mouse on
# These are technically covered by `set -g mouse on`, but explicit is sometimes clearer
# set -g mouse-resize-pane on
# set -g mouse-select-pane on
# set -g mouse-select-text on
set -g mouse-wheel on
The true power emerges when you combine mouse support with tmux’s window and pane management. For example, you can click on a tab to switch to a different window, or double-click a pane border to make that pane fullscreen.
A common point of confusion is when mouse support doesn’t seem to work. Often, this is because the terminal emulator itself is intercepting mouse events before they reach tmux. Make sure your terminal emulator’s settings are configured to pass mouse events through to the application. For example, in iTerm2 on macOS, you’d check Preferences > Profiles > [Your Profile] > Terminal > Emulate terminal with xterm mouse reporting. In GNOME Terminal, it’s usually enabled by default.
The most surprising thing is how seamlessly tmux integrates mouse actions with its keyboard-centric workflow. You don’t have to choose between them; you can fluidly switch between clicking to select a pane and then using keyboard shortcuts to split it or send commands. It’s not just about making things easier; it’s about making complex layouts and workflows more accessible at a glance.
The next step after mastering mouse support is exploring how tmux’s copy-paste buffer interacts with your system clipboard, which often involves additional configuration or external tools.