Skip to main content
WezTerm provides a searchable scrollback buffer that allows you to review terminal output that has scrolled off the screen. The scrollback buffer has a configurable size limit and supports powerful search capabilities.

​
Scrollback Buffer

As content is printed to the terminal, lines that scroll off the top are moved into the scrollback buffer where they can be reviewed by scrolling up.

​
Configuring Scrollback Size

Control how many lines of history are retained:
Configure Scrollback Lines
local wezterm = require 'wezterm'
local config = {}

-- Number of lines to retain per tab
config.scrollback_lines = 3500

return config
Larger scrollback values require more memory. If you have many long-lived tabs, consider the impact on system RAM when setting this value.

​
Scrollbar Configuration

Enable or disable the visual scrollbar:
Enable Scrollbar
-- Enable the scrollbar
-- It will occupy the right window padding space
config.enable_scroll_bar = true
You can customize the scrollbar colors in your color scheme configuration.

​
Keyboard Navigation

ActionKeybinding
Scroll up one pageShift+PageUp
Scroll down one pageShift+PageDown
Scroll with mouse wheelMouse Wheel

​
Programmatic Scrolling

Custom Scroll Bindings
local wezterm = require 'wezterm'
local act = wezterm.action
local config = {}

config.keys = {
  {
    key = 'PageUp',
    mods = 'SHIFT',
    action = act.ScrollByPage(-1),
  },
  {
    key = 'PageDown',
    mods = 'SHIFT',
    action = act.ScrollByPage(1),
  },
}

return config

​
Searching the Scrollback

WezTerm includes a powerful search overlay that lets you find text in your scrollback buffer.

​
Activating Search Mode

PlatformKeybinding
macOSCmd+F
Linux/WindowsCtrl+Shift+F

​
Search Mode Controls

When the search overlay is active:
ActionKeybinding
Type to searchAny character
Find previous matchEnter, UpArrow, Ctrl+P
Find next matchCtrl+N, DownArrow
Previous page of matchesPageUp
Next page of matchesPageDown
Toggle search modeCtrl+R (cycles: case-sensitive → ignore case → regex)
Clear search patternCtrl+U
Copy selected matchCtrl+Shift+C
Exit searchEscape

​
Search Modes

Press Ctrl+R to cycle through three search modes:
  1. Case-sensitive text matching - Exact case match
  2. Case-insensitive matching - Ignores case differences
  3. Regular expression - Uses Rust regex syntax
The current mode is indicated in the search bar.

​
Saved Searches

Create keybindings to search for common patterns instantly.
Search for Git Hashes
local wezterm = require 'wezterm'
local config = {}

config.keys = {
  -- Search for things that look like git hashes
  {
    key = 'H',
    mods = 'SHIFT|CTRL',
    action = wezterm.action.Search { Regex = '[a-f0-9]{6,}' },
  },
}

return config
1

Press Ctrl+Shift+H

Activates the search and highlights all git hashes.
2

Navigate with Enter/Ctrl+N/Ctrl+P

Cycle through the highlighted hashes.
3

Copy with Ctrl+Shift+C

Copy the selected hash to the clipboard.
4

Paste with Ctrl+Shift+V

Paste the hash where needed.

​
More Saved Search Examples

config.keys = {
  {
    key = 'I',
    mods = 'SHIFT|CTRL',
    action = wezterm.action.Search { 
      Regex = '[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3}' 
    },
  },
}

​
Clearing the Scrollback

Remove all scrollback history from the current tab:
PlatformKeybinding
macOSCmd+K
Linux/WindowsCtrl+Shift+K
Clearing the scrollback buffer is permanent and cannot be undone.

​
Custom Clear Binding

Custom Clear Scrollback
config.keys = {
  {
    key = 'K',
    mods = 'CTRL|SHIFT',
    action = wezterm.action.ClearScrollback 'ScrollbackAndViewport',
  },
}

​
Customizing Search Mode

You can customize the key bindings for search mode by overriding the search_mode key table:
Custom Search Bindings
local wezterm = require 'wezterm'
local act = wezterm.action
local config = {}

-- Get default key tables
config.key_tables = wezterm.gui.default_key_tables()

-- Customize search_mode table
config.key_tables.search_mode = {
  { key = 'Enter', mods = 'NONE', action = act.CopyMode 'PriorMatch' },
  { key = 'Escape', mods = 'NONE', action = act.CopyMode 'Close' },
  -- Add your custom bindings here
}

return config

​
Performance Considerations

  • Memory usage increases with scrollback_lines setting
  • Search performance depends on scrollback size and pattern complexity
  • Consider reducing scrollback size for resource-constrained systems
  • Regular expressions are more powerful but can be slower than simple text searches
Scrollback search integrates with Copy Mode for keyboard-driven text selection and copying workflows.