TmuxAI Logo

Tmux

AI

Home→Tmux FAQ

How to increase scrollback buffer in tmux?

Quick Answer

To increase tmux scrollback buffer size, add set -g history-limit 10000 to your ~/.tmux.conf file (adjust the number to your desired limit). This setting controls how many lines of output each pane remembers. After adding this line, either restart tmux or reload your configuration with Ctrl+b : source-file ~/.tmux.conf. 

echo "set -g history-limit 10000" >> ~/.tmux.conf

# Then reload config
Ctrl+b :source-file ~/.tmux.conf

Detailed Explanation

The scrollback buffer in tmux determines how many lines of terminal output are retained in memory for each pane. Increasing this limit allows you to scroll back further in your terminal history, which is particularly useful for reviewing log outputs, command results, or long-running processes.

Understanding the Scrollback Buffer

By default, tmux sets the scrollback buffer to 2000 lines per pane. This means each pane can "remember" the last 2000 lines of output. Once this limit is reached, the oldest lines are discarded to make room for new output.

terminal
Line 1: Old output that will be lost
Line 2: Old output that will be lost
...
Line 1998: Visible with default limit
Line 1999: Visible with default limit
Line 2000: Visible with default limit
Line 2001: Only visible with increased limit
Line 2002: Only visible with increased limit
...
Line 10000: Only visible with increased limit
Default limit (2000 lines)
Increased limit (10000+ lines)

For many use cases, especially when working with verbose logs or compilers, this default limit may be too small. Increasing it allows you to retain more history and reduces the chance of losing important information.

Configuring the Scrollback Size

To permanently change the scrollback buffer size, add this line to your ~/.tmux.conf file:

~/.tmux.conf
1
# Default tmux settings
2
set -g default-terminal "screen-256color"
3
set -g status-keys vi
4
5
# Increase scrollback buffer size
6
set -g history-limit 10000
7
8
# Other settings

You can choose any number based on your needs and available memory. Common values range from 5,000 to 50,000 lines. The -g flag makes this a global setting that applies to all sessions.

Applying the Configuration

After adding the line to your configuration file, you have two options to apply the change:

  1. Restart tmux: Exit all sessions and start tmux again
  2. Reload configuration: Within tmux, press Ctrl+b : and type source-file ~/.tmux.conf

Note that changing this setting only affects new panes and windows. Existing panes will keep their current history-limit setting until they are closed and reopened.

Checking Current Scrollback Size

To check the current scrollback buffer size setting: 

# In tmux command mode (Ctrl+b :)
show-options -g history-limit

Memory Considerations

Increasing the scrollback buffer significantly will increase tmux's memory usage. Each line in the scrollback buffer consumes memory, so very large values (100,000+) can lead to high memory consumption, especially if you have many panes open.

Memory Usage Comparison
Default (2,000 lines)~1MB per pane
Moderate (10,000 lines)~5MB per pane
Large (30,000 lines)~15MB per pane
Extreme (100,000+ lines)50MB+ per pane
* Memory usage is approximate and varies based on content complexity

As a rough guideline:

  • 5,000-10,000 lines: Good balance for most users
  • 20,000-30,000 lines: Better for developers working with verbose outputs
  • 50,000+ lines: For specific use cases where extensive history is required

Using Copy Mode with Scrollback

To access and navigate through your scrollback buffer:

Copy Mode Navigation
Enter & Exit
Ctrl+bthen[Enter copy mode
qExit copy mode
Basic Navigation
↑Up one line
↓Down one line
PgUpPage up
PgDnPage down
Search (Vim mode)
/Forward search
?Backward search
nNext match
Search (Emacs mode)
Ctrl+sForward search
Ctrl+rBackward search
Tip: With a larger scrollback buffer, you'll have more content to search through in copy mode!
  1. Enter copy mode by pressing Ctrl+b [
  2. Use arrow keys, Page Up/Down, or Vim/Emacs navigation keys to scroll
  3. Search the buffer with Ctrl+r (reverse search) or Ctrl+s (forward search) in Emacs mode, or / (forward) and ? (backward) in Vim mode
  4. Exit copy mode with q

PRO TIP|Saving Unlimited History

For exceptionally large output that exceeds even a large scrollback buffer, you can capture the pane contents to a file:

terminal
# In tmux command mode (Ctrl+b :)
capture-pane -S -
save-buffer ~/output.txt

# Or from your shell
tmux capture-pane -pS - > ~/output.txt

The -S - option tells tmux to capture from the start of the scrollback buffer. This technique works regardless of your history-limit setting.

←Back to FAQ Index