tmux Clipboard Integration: Copy to System Clipboard (2026)

tmux clipboard integration is surprisingly difficult because tmux is designed to be a self-contained terminal multiplexer, not an intermediary for system-wide clipboard operations.

Here’s how you can see it in action, and then we’ll break down why it’s complicated and how to solve it.

Imagine you’re in a tmux session, working on a remote server. You’ve got a long command output you need to copy.

# Inside tmux session
ls -l /usr/share/doc

You select the output, but when you try to paste it into your local editor, it’s empty or contains garbage. This is the problem we’re solving.

The core issue is that tmux itself doesn’t have direct access to your operating system’s clipboard. It operates within its own isolated environment. When you "copy" text within tmux using its built-in copy mode, that text is stored in tmux’s internal buffer, not your system’s clipboard. To get it out, you need a bridge.

The most common and robust solution involves xclip or xsel on Linux/BSD systems, or pbcopy on macOS. These are command-line utilities that interact with the X Window System (or Wayland) clipboard or the macOS pasteboard.

1. Installing the Clipboard Tools

First, ensure you have the necessary tools installed on the client machine (where your terminal emulator is running).

• Debian/Ubuntu:

  sudo apt update && sudo apt install xclip
  

• Fedora/CentOS/RHEL:

  sudo dnf install xclip
  

• macOS: pbcopy is built-in.

2. Configuring tmux

You need to tell tmux to pipe its copy buffer to these external tools. This is done in your ~/.tmux.conf file.

Add these lines to your ~/.tmux.conf:

# Copy mode binding to copy to system clipboard
bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "xclip -selection clipboard"
bind-key -T copy-mode-emacs y send-keys -X copy-pipe-and-cancel "xclip -selection clipboard"

# For macOS:
# bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "pbcopy"
# bind-key -T copy-mode-emacs y send-keys -X copy-pipe-and-cancel "pbcopy"

• bind-key -T copy-mode-vi y: This binds the y key in vi mode within tmux’s copy mode.
• send-keys -X copy-pipe-and-cancel: This is the tmux command to send keys. copy-pipe-and-cancel means it will execute a command, pipe the selected text to it, and then exit copy mode.
• "xclip -selection clipboard": This is the command that receives the piped text. xclip is invoked with -selection clipboard to target the primary clipboard (the one you typically use with Ctrl+C/Cmd+C and Ctrl+V/Cmd+V). If you want to use the secondary (middle-click paste) selection, use xclip -selection primary.

After saving ~/.tmux.conf, reload your tmux configuration:

# Inside tmux
tmux source-file ~/.tmux.conf

Or, restart your tmux server.

3. How it Works (The Mental Model)

When you enter tmux’s copy mode (e.g., Ctrl+b [), navigate to the text you want, and press y (in vi mode), tmux does the following:

1. It captures the selected text.
2. It executes the command specified in copy-pipe-and-cancel (xclip -selection clipboard).
3. It pipes the captured text directly to the standard input of that command.
4. xclip receives this text and places it onto the X selection buffer.
5. tmux exits copy mode.

Now, when you switch to another application on your local machine and press Ctrl+V (or Cmd+V), the application requests the content of the clipboard from the operating system, which xclip populated.

4. Troubleshooting Common Issues

• xclip: command not found (or similar): This means xclip isn’t installed on your local machine, or it’s not in your PATH. Install it using your package manager.
• Copying works, but pasting is empty/garbage:
  • Remote vs. Local: Double-check that xclip is installed and configured on your local machine, not the remote server you’re SSH’d into. The copy-pipe command runs on the client side where tmux is executing.
  • SSH X11 Forwarding: If you’re using SSH and copying from a remote tmux session to your local machine, you might need X11 forwarding enabled (ssh -X or ssh -Y). However, the copy-pipe method bypasses the need for X11 forwarding between the remote server and your local machine for the clipboard data itself, because tmux on the client is piping to a local xclip. The issue is usually that xclip isn’t installed locally, or the tmux.conf is on the remote machine instead of the local one.
  • Wayland: If you’re on a Wayland session, xclip might not work directly. You might need wl-copy (from wl-clipboard). The tmux.conf would then look like:

    bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "wl-copy"
    bind-key -T copy-mode-emacs y send-keys -X copy-pipe-and-cancel "wl-copy"
    

    Install it with sudo apt install wl-clipboard (Debian/Ubuntu) or sudo dnf install wl-clipboard (Fedora).
  • Tmux Configuration Not Loaded: Ensure you reloaded your tmux config (tmux source-file ~/.tmux.conf) or restarted tmux.
  • Incorrect Key Binding: Verify the key binding in ~/.tmux.conf matches your copy mode style (vi or emacs).
• Copying large amounts of data: If you’re copying gigabytes of data, this method might be slow or hit buffer limits. For very large data transfers, consider alternative methods like scp, rsync, or screen sharing.

The most overlooked aspect is often that the copy-pipe command executes on the client machine. If your tmux.conf is configured on the remote server, it’s trying to pipe to xclip on the server, which doesn’t help your local clipboard. Ensure your ~/.tmux.conf is active for your local tmux sessions.

The next hurdle is often configuring mouse support within tmux to select text more intuitively.