Searchable Scrollback

Navigate and search through terminal history with WezTerm’s powerful scrollback buffer

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.

Navigating the Scrollback

Keyboard Navigation

Action	Keybinding
Scroll up one page	Shift+PageUp
Scroll down one page	Shift+PageDown
Scroll with mouse wheel	Mouse 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

Platform	Keybinding
macOS	Cmd+F
Linux/Windows	Ctrl+Shift+F

Search Mode Controls

When the search overlay is active:

Action	Keybinding
Type to search	Any character
Find previous match	Enter, UpArrow, Ctrl+P
Find next match	Ctrl+N, DownArrow
Previous page of matches	PageUp
Next page of matches	PageDown
Toggle search mode	Ctrl+R (cycles: case-sensitive → ignore case → regex)
Clear search pattern	Ctrl+U
Copy selected match	Ctrl+Shift+C
Exit search	Escape

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.

Example: Git Hash Search

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

IP Addresses

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:

Platform	Keybinding
macOS	Cmd+K
Linux/Windows	Ctrl+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

Related Features

Scrollback search integrates with Copy Mode for keyboard-driven text selection and copying workflows.