> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wezterm/wezterm/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```lua Configure Scrollback Lines theme={null}
local wezterm = require 'wezterm'
local config = {}

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

return config
```

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

### Scrollbar Configuration

Enable or disable the visual scrollbar:

```lua Enable Scrollbar theme={null}
-- 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

```lua Custom Scroll Bindings theme={null}
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](https://docs.rs/regex/latest/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

```lua Search for Git Hashes theme={null}
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
```

<Steps>
  <Step title="Press Ctrl+Shift+H">
    Activates the search and highlights all git hashes.
  </Step>

  <Step title="Navigate with Enter/Ctrl+N/Ctrl+P">
    Cycle through the highlighted hashes.
  </Step>

  <Step title="Copy with Ctrl+Shift+C">
    Copy the selected hash to the clipboard.
  </Step>

  <Step title="Paste with Ctrl+Shift+V">
    Paste the hash where needed.
  </Step>
</Steps>

### More Saved Search Examples

<CodeGroup>
  ```lua IP Addresses theme={null}
  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}' 
      },
    },
  }
  ```

  ```lua UUIDs theme={null}
  config.keys = {
    {
      key = 'U',
      mods = 'SHIFT|CTRL',
      action = wezterm.action.Search { 
        Regex = '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}' 
      },
    },
  }
  ```

  ```lua Error Messages theme={null}
  config.keys = {
    {
      key = 'E',
      mods = 'SHIFT|CTRL',
      action = wezterm.action.Search { 
        CaseInSensitiveString = 'error' 
      },
    },
  }
  ```
</CodeGroup>

## Clearing the Scrollback

Remove all scrollback history from the current tab:

| Platform      | Keybinding     |
| ------------- | -------------- |
| macOS         | `Cmd+K`        |
| Linux/Windows | `Ctrl+Shift+K` |

<Warning>
  Clearing the scrollback buffer is permanent and cannot be undone.
</Warning>

### Custom Clear Binding

```lua Custom Clear Scrollback theme={null}
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:

```lua Custom Search Bindings theme={null}
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](/features/copy-mode) for keyboard-driven text selection and copying workflows.