tmux Copy Mode: Copy, Paste & Clipboard Guide

What is Copy Mode?

tmux copy mode allows you to scroll through terminal output, search for text, and copy content to a buffer or your system clipboard. It is essential when you need to copy output from the terminal without reaching for the mouse.

By default, tmux does not let you scroll back through the output of a pane. Copy mode solves this by turning the current pane into a scrollable buffer where you can navigate, select, and copy text using keyboard shortcuts.

Once inside copy mode, you can freely move around the buffer, search for text, select regions, and copy them. The copied text is stored in a tmux paste buffer and can also be sent to your system clipboard with the right configuration.

Vi vs Emacs Mode

tmux supports two key binding styles for copy mode: vi and emacs. The default is emacs mode. If you are a vim user, switching to vi mode is highly recommended as the key bindings will feel natural and consistent with your editor workflow.

# Set vi mode for copy mode key bindings (recommended for vim users)
setw -g mode-keys vi

# Set emacs mode (this is the default)
setw -g mode-keys emacs

# Check current mode
tmux show-option -gw mode-keys

Add the setw -g mode-keys vi line to your ~/.tmux.conf to make it persistent. This guide primarily covers vi mode key bindings, with emacs equivalents noted where appropriate.

Navigation in Copy Mode

Once you enter copy mode with prefix + [, you can navigate through the buffer using the following keys depending on your mode setting.

Vi Mode Navigation

Emacs Mode Navigation

Selecting and Copying Text

In vi mode, selecting and copying text follows a flow similar to vim's visual mode. You navigate to the start of the text you want, begin a selection, move to the end, and then yank (copy) it.

The default key bindings for selection in vi mode can be improved by adding vim-like bindings. Here is the recommended configuration to add to your ~/.tmux.conf:

# Enable vi mode
setw -g mode-keys vi

# vim-like selection key bindings
bind -T copy-mode-vi v send-keys -X begin-selection
bind -T copy-mode-vi y send-keys -X copy-selection-and-cancel
bind -T copy-mode-vi C-v send-keys -X rectangle-toggle

With this configuration, the copy workflow becomes:

1. Press prefix + [ to enter copy mode
2. Navigate to the start of the text you want to copy
3. Press v to begin selection (or V for line selection)
4. Move to the end of the text to extend the selection
5. Press y to yank (copy) the selection
6. Press prefix + ] to paste

System Clipboard Integration

By default, tmux copies text to its own internal paste buffer, not to your system clipboard. To integrate with the system clipboard, you need to pipe the copied text to a clipboard command specific to your operating system.

macOS (pbcopy)

On macOS, use pbcopy to send copied text to the system clipboard:

# macOS: copy to system clipboard
bind -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "pbcopy"

# Also copy on mouse drag end (if mouse mode is enabled)
bind -T copy-mode-vi MouseDragEnd1Pane send-keys -X copy-pipe-and-cancel "pbcopy"

Linux X11 (xclip / xsel)

On Linux with X11, use xclip or xsel to access the system clipboard:

# Linux X11 with xclip
bind -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "xclip -selection clipboard"

# Linux X11 with xsel (alternative)
bind -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "xsel --clipboard --input"

# Install xclip or xsel if not present
# Debian/Ubuntu: sudo apt install xclip
# Fedora: sudo dnf install xclip
# Arch: sudo pacman -S xclip

Linux Wayland (wl-copy)

On Linux with Wayland, use wl-copy from the wl-clipboard package:

# Linux Wayland
bind -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "wl-copy"

# Install wl-clipboard if not present
# Debian/Ubuntu: sudo apt install wl-clipboard
# Fedora: sudo dnf install wl-clipboard
# Arch: sudo pacman -S wl-clipboard

Cross-Platform Configuration

If you use the same ~/.tmux.conf across macOS and Linux machines, you can use if-shell to automatically detect the platform and choose the correct clipboard command:

# Cross-platform clipboard integration
if-shell "uname | grep -q Darwin" \
  'bind -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "pbcopy"' \
  'bind -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "xclip -selection clipboard"'

As an easier alternative, the tmux-yank plugin automatically detects your platform and configures clipboard integration for you. If you use TPM (Tmux Plugin Manager), simply add it to your plugin list:

# Add to ~/.tmux.conf
set -g @plugin 'tmux-plugins/tmux-yank'

# Then install with: prefix + I

Searching in Copy Mode

Copy mode includes a search feature that works similarly to vim search. This is useful for finding specific text in your scrollback buffer, such as error messages or log entries.

# Example search workflow:
# 1. Enter copy mode: prefix + [
# 2. Press / to start forward search
# 3. Type your search term and press Enter
# 4. Press n to jump to the next match
# 5. Press N to jump to the previous match
# 6. Press q to exit copy mode

In emacs mode, use Ctrl+s for forward search and Ctrl+r for reverse search. The n and N keys work the same way to cycle through matches.

Buffer Management

tmux maintains a stack of paste buffers. Every time you copy text in copy mode, it is pushed onto this buffer stack. You can list, view, save, and paste from these buffers using tmux commands.

# List all paste buffers with their contents
tmux list-buffers

# Show the content of the most recent buffer
tmux show-buffer

# Save the most recent buffer to a file
tmux save-buffer ~/copied-output.txt

# Save a specific buffer (by index) to a file
tmux save-buffer -b 0 ~/buffer0.txt

# Load a file into the paste buffer
tmux load-buffer ~/some-text.txt

# Delete all buffers
tmux delete-buffer -a

The buffer chooser (prefix + =) opens an interactive list where you can preview each buffer and select one to paste. This is especially useful when you have copied multiple pieces of text and need to paste an earlier selection.

Practical Examples

Here are common real-world scenarios where copy mode is indispensable.

Copying a Command Output

When you run a command and need to copy part of its output (for example, a file path or a hash), copy mode lets you do it entirely from the keyboard:

# 1. Run your command
git log --oneline -5

# 2. Enter copy mode: prefix + [
# 3. Navigate to the commit hash you want (use k to go up, w to move by word)
# 4. Press v to start selection
# 5. Move to select the hash (e.g., press e to go to end of word)
# 6. Press y to copy
# 7. Paste with: prefix + ]

Copying an Error Message

Error messages often span multiple lines. Use line selection to grab the whole block:

# 1. Enter copy mode: prefix + [
# 2. Navigate to the first line of the error
# 3. Press V to start line selection
# 4. Press j to extend the selection down across all error lines
# 5. Press y to copy all selected lines
# 6. Paste into a bug report or chat with: prefix + ]

Searching for a Specific Log Entry

When debugging, you often need to find a specific log entry in a long output stream:

# 1. Enter copy mode: prefix + [
# 2. Press ? to search backward (since errors are usually recent)
# 3. Type "ERROR" and press Enter
# 4. Press n/N to cycle through matches until you find the right one
# 5. Press v to start selection, then navigate to select the relevant text
# 6. Press y to copy

Copying Multi-Line Content

Rectangle (block) selection is useful when you need to copy a column of data from formatted output:

# 1. Enter copy mode: prefix + [
# 2. Navigate to the top-left corner of the block you want
# 3. Press Ctrl+v to toggle rectangle selection mode
# 4. Press v to start selection
# 5. Navigate to the bottom-right corner of the block
# 6. Press y to copy the rectangular selection

# Vi mode for copy mode
setw -g mode-keys vi

# vim-like key bindings for selection
bind -T copy-mode-vi v send-keys -X begin-selection
bind -T copy-mode-vi C-v send-keys -X rectangle-toggle
bind -T copy-mode-vi V send-keys -X select-line

# System clipboard integration (choose your platform)
# macOS
if-shell "uname | grep -q Darwin" \
  'bind -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "pbcopy"'

# Linux (X11)
if-shell "[ -n \"\$DISPLAY\" ]" \
  'bind -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "xclip -selection clipboard"'

# Increase scrollback buffer size (default is 2000)
set -g history-limit 50000