How to Enable and Use Scroll in tmux Terminal

by

The power of tmux lies in its flexibility to manage multiple terminal sessions efficiently. While tmux is mostly used for splitting terminal windows and multiplexing shell sessions, one essential yet often misunderstood feature is scrolling. By default, scrolling in tmux can feel unintuitive for users unfamiliar with its structure, especially for those used to standard terminal behavior. This article explores how to enable scrolling in tmux, how to interact with the scrollback buffer, and how to use this feature effectively for day-to-day development and system administration tasks.

Understanding Scrollback in tmux

tmux, unlike traditional terminal emulators, maintains its own buffer for scrollback content. This means if a command outputs more lines than can fit in the current visible window, those lines are still accessible—just not via native terminal scroll. You need to access them through tmux’s “copy mode.”

Enabling Mouse Support for Scrolling

To enable scrolling using a mouse, tmux must be configured correctly. This feature is available in tmux 2.1 and later with better support in newer versions.

Step 1: Modify the tmux Configuration File

You need to enable mouse support in your ~/.tmux.conf file. Open this file in your preferred text editor and add the following line:

set -g mouse on

After you’ve added this line, reload the config with the following command from within a tmux session:

tmux source-file ~/.tmux.conf

Step 2: Using the Mouse to Scroll

Once mouse mode is active, you can scroll using your mouse wheel or touchpad, similar to other terminal emulators. This activates tmux’s “copy mode” automatically when you initiate a scroll with your mouse.

Manual Scrolling Using Copy Mode

If you’re accessing tmux via SSH or do not have mouse control, you’re still able to scroll using keyboard shortcuts via tmux’s copy mode.

Step 1: Enter Copy Mode

To enter copy mode, press the following key combination:

Ctrl + b, then [

This tells tmux you want to start interacting with the scrollback buffer.

Step 2: Moving Through the Buffer

Once in copy mode, you can use standard navigation keys:

  • Up/Down Arrow: Move line-by-line
  • Page Up/Page Down: Scroll faster by pages
  • G: Jump to the bottom
  • g: Jump to the top

Exiting Copy Mode

To exit copy mode, press q. This will return you to your regular input mode within the tmux pane.

Copying Text in Scrollback Buffer

Scrolling is only part of the functionality. A crucial benefit of tmux is being able to select and copy text from the buffer.

Step 1: Enter Copy Mode Again

Using Ctrl + b then [, enter copy mode as described.

Step 2: Start Selection

Navigate to the beginning of the text you want to copy. Press Space to start the selection process.

Step 3: Finish and Copy

Move to the end of the text you want to copy using arrow keys. Once you’re done, press Enter. The text is now copied and ready to be pasted within tmux buffers using Ctrl + b followed by ].

Adjusting the Scrollback Buffer Size

Another helpful tip is increasing the history limit so you can scroll through more lines.

Edit your ~/.tmux.conf file and add:

set -g history-limit 100000

This increases the scrollback buffer to 100,000 lines. Reapply the configuration:

tmux source-file ~/.tmux.conf

tmux terminal scrolling history lines config[/ai-img>

Terminal Emulator vs tmux Scrolling

Many users get confused when trying to use their terminal emulator’s scroll feature while inside tmux. Once tmux is running, its buffer overrides that of your terminal emulator. This means traditional scrolling won’t work until you configure either mouse support or activate copy mode manually.

Useful Tips

  • Clipboard Integration: You can integrate tmux with your system clipboard using tools like xclip or reattach-to-user-namespace on macOS.
  • Key Remapping: Consider remapping keys for easier access to copy mode or paste functionality.
  • Use Vim Keys: tmux supports vim-style keybindings in copy mode, making it more efficient for vim users.

Alternatives and Plugins

For enhanced functionality, users often use plugins like tmux-yank which helps integrate system clipboard access and improves usability of copy-paste functionality within scrollback buffers.

Common Scenarios Where Scrolling is Helpful

  • Reviewing long logs from scripts or servers
  • Examining output after running commands like git diff
  • Finding and copying error messages for debugging or support

Conclusion

Understanding how to scroll within a tmux session is a core part of mastering this powerful terminal multiplexer. Whether it’s enabling mouse support for intuitive scrolling or navigating copy mode with keyboard shortcuts, these techniques can transform your terminal productivity. With time and practice, these methods become second nature and offer workflow improvements unmatched by typical terminal behavior.

Frequently Asked Questions (FAQ)

  • Q: Why can’t I scroll up in tmux using my mouse?
    A: Mouse support must be explicitly enabled in the tmux configuration by setting set -g mouse on. Without this line, tmux will ignore mouse scroll actions.
  • Q: How do I view previous output in tmux without a mouse?
    A: Use Ctrl + b followed by [ to enter copy mode. You can then scroll using arrow keys or Page Up/Page Down.
  • Q: Can I increase how much tmux lets me scroll up?
    A: Yes, set set -g history-limit <number> in your tmux config file. A value like 100000 gives you ample scrollback capability.
  • Q: How do I copy text in tmux?
    A: Enter copy mode, press Space to mark the beginning of the selection, navigate to the end, and press Enter. Then paste using Ctrl + b and ].
  • Q: Will tmux mouse scrolling still work over SSH?
    A: Yes, provided the client supports mouse interactions and the tmux config enables it. Some terminals or SSH clients may restrict mouse support by default.