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

# Copy Mode

> Keyboard-driven text selection with Vim-style navigation for efficient terminal interaction

Copy mode allows you to select and copy text from your terminal using only the keyboard, with Vim-style navigation controls. This eliminates the need to reach for your mouse when selecting terminal output.

## Activating Copy Mode

| Action             | Keybinding     |
| ------------------ | -------------- |
| Activate copy mode | `Ctrl+Shift+X` |

When copy mode is active, the tab title is prefixed with "Copy Mode" and the terminal behavior changes to allow keyboard-driven cursor navigation.

## Selection Modes

Copy mode supports three types of selection:

| Mode                  | Keybinding | Description                  |
| --------------------- | ---------- | ---------------------------- |
| Cell selection        | `v`        | Select individual characters |
| Line selection        | `Shift+V`  | Select entire lines          |
| Rectangular selection | `Ctrl+V`   | Select a rectangular block   |

<Note>
  Selection mode is off by default. Press `v` to toggle it on before selecting text.
</Note>

## Navigation

### Basic Movement

| Action     | Keybindings       |
| ---------- | ----------------- |
| Move left  | `h`, `LeftArrow`  |
| Move down  | `j`, `DownArrow`  |
| Move up    | `k`, `UpArrow`    |
| Move right | `l`, `RightArrow` |

### Word Movement

| Action              | Keybindings                                |
| ------------------- | ------------------------------------------ |
| Forward one word    | `w`, `Alt+F`, `Alt+RightArrow`, `Tab`      |
| Backward one word   | `b`, `Alt+B`, `Alt+LeftArrow`, `Shift+Tab` |
| Forward to word end | `e`                                        |

### Line Movement

| Action                 | Keybindings  |
| ---------------------- | ------------ |
| Start of line          | `0`, `Home`  |
| End of line            | `$`, `End`   |
| Start of next line     | `Enter`      |
| Start of indented line | `^`, `Alt+M` |

### Viewport Movement

| Action             | Keybindings |
| ------------------ | ----------- |
| Top of viewport    | `Shift+H`   |
| Middle of viewport | `Shift+M`   |
| Bottom of viewport | `Shift+L`   |

### Page Movement

| Action           | Keybindings          |
| ---------------- | -------------------- |
| Up one screen    | `PageUp`, `Ctrl+B`   |
| Down one screen  | `PageDown`, `Ctrl+F` |
| Up half screen   | `Ctrl+U`             |
| Down half screen | `Ctrl+D`             |

### Scrollback Movement

| Action               | Keybindings       |
| -------------------- | ----------------- |
| Top of scrollback    | `g` (press twice) |
| Bottom of scrollback | `Shift+G`         |

## Selection Actions

### Copying Text

| Action              | Keybinding     |
| ------------------- | -------------- |
| Copy and exit       | `y`            |
| Copy (without exit) | `Ctrl+Shift+C` |

### Adjusting Selection

| Action                         | Keybinding |
| ------------------------------ | ---------- |
| Move to other end of selection | `o`        |
| Move to other end horizontally | `Shift+O`  |

<Note>
  `Shift+O` is particularly useful in rectangular selection mode for adjusting the selection boundary.
</Note>

### Exiting Copy Mode

| Action         | Keybindings                       |
| -------------- | --------------------------------- |
| Exit copy mode | `Escape`, `Ctrl+C`, `Ctrl+G`, `q` |

## Workflow Example

<Steps>
  <Step title="Activate copy mode">
    Press `Ctrl+Shift+X` to enter copy mode.
  </Step>

  <Step title="Navigate to start position">
    Use `h`, `j`, `k`, `l` or arrow keys to move the cursor to where you want to start selecting.
  </Step>

  <Step title="Start selection">
    Press `v` for character selection, `Shift+V` for line selection, or `Ctrl+V` for rectangular selection.
  </Step>

  <Step title="Extend selection">
    Move the cursor to the end of the text you want to select.
  </Step>

  <Step title="Copy and exit">
    Press `y` to copy the selected text and exit copy mode, or `Ctrl+Shift+C` to copy without exiting.
  </Step>
</Steps>

## Customizing Copy Mode

You can customize copy mode keybindings by overriding the `copy_mode` key table:

```lua Custom Copy Mode 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 specific bindings in copy_mode
table.insert(config.key_tables.copy_mode, {
  key = 'c',
  mods = 'CTRL',
  action = act.CopyMode 'Close',
})

return config
```

### View Default Copy Mode Bindings

To see all default copy mode keybindings:

```bash View Copy Mode Keys theme={null}
wezterm show-keys --lua --key-table copy_mode
```

## Color Customization

Customize the appearance of selected text in copy mode:

```lua Copy Mode Colors theme={null}
local wezterm = require 'wezterm'
local config = {}

config.colors = {
  copy_mode_active_highlight_bg = { Color = '#000000' },
  copy_mode_active_highlight_fg = { Color = '#ffffff' },
  copy_mode_inactive_highlight_bg = { Color = '#52ad70' },
  copy_mode_inactive_highlight_fg = { Color = '#c0c0c0' },
}

return config
```

## Advanced Usage

### Quick Copy Git Commit Hash

<CodeGroup>
  ```lua Using Copy Mode theme={null}
  -- 1. Run git log
  -- 2. Ctrl+Shift+X to enter copy mode  
  -- 3. Navigate to the commit hash
  -- 4. Press 'w' repeatedly to select the hash (moves word by word)
  -- 5. Press 'v' to start selection
  -- 6. Press 'e' to extend to end of word
  -- 7. Press 'y' to copy
  ```

  ```lua Using Search Instead theme={null}
  -- Even faster: use saved search
  config.keys = {
    {
      key = 'H',
      mods = 'SHIFT|CTRL',
      action = wezterm.action.Search { Regex = '[a-f0-9]{6,}' },
    },
  }
  ```
</CodeGroup>

### Selecting Command Output

```lua Example Workflow theme={null}
-- 1. Run a command that produces output
-- 2. Ctrl+Shift+X to enter copy mode
-- 3. 'gg' to go to top of scrollback
-- 4. Search forward for command prompt or output start
-- 5. 'V' for line selection mode
-- 6. 'j' or '}' to select lines
-- 7. 'y' to copy
```

## Integration with Quick Select

While copy mode provides fine-grained control, [Quick Select](/features/quick-select) mode is better for quickly selecting common patterns like:

* URLs
* File paths
* Git hashes
* IP addresses

Use copy mode when you need:

* Precise character-level selection
* Multi-line selections
* Rectangular selections
* Vim-style navigation

## Comparison to Other Tools

| Feature                 | Copy Mode            | tmux copy-mode | screen copy mode |
| ----------------------- | -------------------- | -------------- | ---------------- |
| Vim-style navigation    | ✓                    | ✓              | ✓                |
| Rectangular selection   | ✓                    | ✓              | ✓                |
| Integrated search       | ✓ (via Ctrl+Shift+F) | ✓              | ✓                |
| Works with mouse        | ✓                    | ✓              | ✓                |
| No external multiplexer | ✓                    | ✗              | ✗                |

## Tips and Tricks

1. **Combine with search**: Use `Ctrl+Shift+F` to search, then `Ctrl+Shift+X` to enter copy mode at the found location

2. **Use markers**: Navigate to specific points quickly with `Shift+H` (top), `Shift+M` (middle), `Shift+L` (bottom)

3. **Rectangular mode for columns**: Use `Ctrl+V` to select columnar data from command output

4. **Fast line grabbing**: `Shift+V` then `j`/`k` for quick line-based selections

5. **Practice Vim motions**: Copy mode is a great way to learn or practice Vim navigation if you're new to it