To enable scrolling in Tmux copy mode, you must enter the prefix key (default Ctrl-B), press [ to activate copy mode, and then use your terminal’s native scroll wheel or keyboard shortcuts like Page Up and Page Down. If scrolling feels unresponsive, verify that your terminal emulator supports mouse events and check your
tmux.conf for conflicting mouse settings. This guide details the standard navigation methods and troubleshooting steps for common configuration issues.
Entering Copy Mode Correctly
The primary step to accessing scrollable history is ensuring you are in the correct mode. Tmux separates normal command input from buffer inspection. Pressing the prefix key followed by
[ enters copy mode. Once inside, the status bar typically changes to indicate this state. Many users attempt to scroll while in normal mode, which results in no visible movement because the pane is waiting for commands, not displaying a buffer.
After entering copy mode, you can navigate using several methods. The most intuitive method for modern setups involves using the mouse wheel. However, this requires specific configuration as discussed later. For keyboard-only navigation,
Page Up and
Page Down move through the buffer one screen at a time. Arrow keys allow pixel-by-pixel movement, which is useful for fine-tuning your view but slower for large buffers.
Configuring Mouse Support
Mouse support is not always enabled by default in older Tmux versions or minimal configurations. To enable it, add the following line to your
~/.tmux.conf file:
set -g mouse on
This single setting activates three features simultaneously: resizing panes, selecting windows, and scrolling in copy mode. After adding this line, reload your configuration by running
tmux source-file ~/.tmux.conf from within a Tmux session. If you prefer granular control, you can use
set -g mouse select-pane on or similar flags, but
mouse on is the standard recommendation for most users.
If you do not see any change after enabling mouse support, the issue likely lies with your terminal emulator rather than Tmux itself. Some terminals require explicit permission to send mouse event codes. For example, in iTerm2, you may need to check "Allow Mouse Reporting" in preferences. In other terminals, ensure that the terminal type is correctly set to
xterm-256color or similar, as generic
xterm types may lack full mouse support.
For those who find the default behavior intrusive, you can disable mouse support entirely by setting
set -g mouse off. This forces reliance on keyboard shortcuts, which some power users prefer for consistency across different environments.
Troubleshooting Unresponsive Scrolling
When scrolling fails despite correct configuration, several factors could be at play. First, verify that you are actually in copy mode. The cursor should be inactive for normal typing. If you accidentally exit copy mode by pressing
q or
Esc, scrolling will stop.
Second, check for conflicts with other plugins or custom bindings. If you have loaded additional scripts via TPM (Tmux Plugin Manager), they might override default behaviors. Look for lines in your config that explicitly set
set -g mouse after plugin loads, as these will take precedence.
Third, consider the size of the scrollback buffer. By default, Tmux limits the history to 2000 lines. If your output exceeds this, older lines are discarded, making it impossible to scroll back further. Increase this limit by adding:
set -g history-limit 10000
Adjust the number based on your system's memory capacity. A higher limit allows deeper scrolling but consumes more RAM.
Finally, ensure your terminal emulator is not intercepting scroll events before they reach Tmux. Some integrated development environments (IDEs) or remote desktop protocols capture mouse inputs locally. Test scrolling in a plain SSH session to isolate whether the problem is local to your client or within the Tmux configuration.
For more advanced navigation techniques, such as using Vim-style bindings, refer to our guide on
Using Vim Shortcuts for Tmux Scrolling. This approach integrates seamlessly with copy mode for users already familiar with Vim motions.
Alternative Navigation Methods
Beyond mouse and basic keyboard shortcuts, Tmux offers powerful search capabilities within copy mode. Pressing
/ initiates a forward search, while
? starts a backward search. You can type a string to highlight matches in the buffer. This is particularly useful for finding specific error messages or log entries without manually scrolling through thousands of lines.
Once a match is found, you can yank (copy) the text by pressing
y. This copies the selected region to the Tmux clipboard, allowing you to paste it into other applications. This feature transforms Tmux into a robust text analysis tool directly within the terminal.
Another useful tip is using
Space to toggle between line mode and cell mode. In line mode, copying includes entire lines, whereas cell mode allows rectangular selections. Understanding these modes enhances productivity when extracting data from structured logs.
If you encounter issues with hyperlinks or colored text disrupting your scroll experience, check out
How to Enable Hyperlinks in TMUX Config File to ensure your visual environment remains stable during heavy usage.
Frequently Asked Questions
Why does my mouse wheel not work in Tmux?
Ensure that
set -g mouse on is present in your
~/.tmux.conf and that you have reloaded the config. Additionally, verify that your terminal emulator supports mouse reporting and has not disabled it in its own settings.
How can I increase the scrollback buffer size?
Add
set -g history-limit [number] to your configuration file, replacing
[number] with your desired line count. Reload the config to apply the change immediately.
Can I use Vim keys to navigate in copy mode?
Yes, by binding keys in your config. Common bindings include mapping
k and
j to move up and down, and
h and
l to move left and right. Use
bind-key k copy-mode-up and similar commands to achieve this.
What is the difference between copy mode and normal mode?
Normal mode accepts commands and interacts with the running process, while copy mode freezes the display and allows navigation through the historical output. You cannot interact with the program in copy mode; you are only viewing saved text.
Does Tmux support scrolling in split panes?
Yes, each pane maintains its own scroll history. When you enter copy mode in a specific pane, only that pane’s buffer becomes accessible for scrolling. Other panes remain unaffected until you switch focus and enter copy mode there as well.