Vim Clipboard Troubleshooting on Linux

Diagnose and fix Vim clipboard failures on Linux with a step‑by‑step guide covering compile flags, helper utilities, environment variables, tmux, SSH, and Wayland.

Problem & Takeaway

When you yank or paste in Vim on Linux, the text never appears in the system clipboard or the terminal’s selection. The most common culprits are missing Vim +clipboard support, absent helper utilities, or environmental mis‑configurations (e.g., $DISPLAY, Wayland, tmux, SSH). The key takeaway: systematically verify Vim’s clipboard capability, ensure the right helper is installed, and confirm the environment is set up for clipboard access.

Diagnostic Table

Condition	Common Cause	Check	Fix	Escalation
"*" and "+" registers are missing	Vim compiled without +clipboard	`vim --version \| grep clipboard`	Re‑compile Vim with +clipboard or install a pre‑built package that includes it.	Check vendor documentation or build logs.
Yank fails to appear in external clipboard	Missing xclip/xsel (X11) or wl-clipboard (Wayland)	`which xclip \|\| which xsel \|\| which wl-clipboard`	Install the appropriate helper: `sudo apt install xclip` or `sudo apt install wl-clipboard`.	Verify helper works: `echo test \| xclip -selection clipboard -o`.
Clipboard commands work in Vim but nothing appears in terminal or GUI	$DISPLAY unset or running under Wayland without XWayland	`echo $DISPLAY`	Set DISPLAY (e.g., `export DISPLAY=:0`) or switch to XWayland, or use wl-clipboard.	Confirm X server is running; use `xset q`.
Copy/paste fails inside tmux	tmux not forwarding clipboard	`tmux show-option -g set-clipboard`	Run `tmux set-option -g set-clipboard on` and reload.	Check tmux version supports set-clipboard; upgrade if needed.
Clipboard unavailable over SSH	Remote session lacks X11 forwarding or clipboard support	`ssh -X user@host`	Enable X11 forwarding in SSH client and server (`X11Forwarding yes`).	Use an alternative like `ssh -C` with `wl-clipboard` over SSH.
Clipboard registers appear but contain wrong data	Vim compiled with -clipboard flag removed support	`vim --version \| grep -E "\+clipboard\|\-clipboard"`	Re‑compile without the -clipboard flag or install a full-featured build.	Consult build configuration logs.

Ordered Checks & Fixes

Verify Vim’s Clipboard Feature
Run inside Vim:
```
:echo has('clipboard')
```
The output should be 1. If 0, Vim lacks clipboard support. Check compile flags:
```
vim --version | grep clipboard
```
If you see +clipboard you’re good; if -clipboard, you need a different build.
Confirm Helper Utility Presence
Depending on your desktop environment, Vim delegates to xclip/xsel (X11) or wl-clipboard (Wayland). Test each:
```
which xclip || which xsel || which wl-clipboard
```
If none are found, install the appropriate package for your distro. For example, on Debian/Ubuntu:
```
sudo apt install xclip
```
Or for Wayland:
```
sudo apt install wl-clipboard
```
Check Environment Variables
For X11 sessions, $DISPLAY must be set. Inside Vim, run:
```
:!echo $DISPLAY
```
If it’s empty, export it in your shell or .vimrc:
```
set clipboard=unnamedplus
```
For Wayland, ensure wl-clipboard is installed and that Vim is compiled with +clipboard. If you’re running inside an XWayland session, $DISPLAY may still be required.
Test Clipboard Round‑Trip
In Vim, yank a line: yy, then paste externally:
```
xclip -o -selection clipboard
```
The output should match the yanked line. If it does not, the helper cannot access the clipboard.
Handle tmux Forwarding
Inside a tmux session, enable clipboard forwarding:
```
tmux set-option -g set-clipboard on
```
Reload tmux configuration or restart the session. Test again with y and xclip -o.
Remote SSH Considerations
When connecting via SSH, use -X or -Y for X11 forwarding:
```
ssh -X user@host
```
Ensure the SSH server allows it (X11Forwarding yes in /etc/ssh/sshd_config). If you’re on Wayland, consider using wl-clipboard with a tool like wl-clipboard over SSH or forwarding the Wayland socket.
Re‑Compile if Necessary
If the build flags show -clipboard, re‑compile Vim with the --enable-clipboard flag or install a pre‑built binary that includes it. Example for Ubuntu:
```
sudo apt install vim-gtk3   # includes +clipboard
# or compile manually
./configure --enable-clipboard
make
sudo make install
```

Practical Verification Checklist

Vim reports has('clipboard') == 1.
Helper utility (xclip/xsel/wl-clipboard) is in PATH.
Running echo $DISPLAY returns a valid display when using X11.
Yank in Vim and read back with the helper shows identical text.
tmux is configured with set-clipboard on if used.
SSH sessions use X11 forwarding or a compatible clipboard tool.

When to Escalate

If after performing all checks the clipboard still fails, consider:

Consulting the distribution’s package manager for a Vim variant with clipboard support.
Checking the terminal emulator’s documentation; some (e.g., alacritty) require explicit clipboard configuration.
Reviewing Wayland compositor logs for clipboard access errors.
Submitting a bug report to the Vim project with the :scriptnames output and system details.

Concrete Example: Fixing a Wayland Clipboard Failure

Scenario: Running Vim in a Wayland session on Fedora. Yanking with +y does nothing; :echo has('clipboard') returns 1, but wl-paste shows nothing.

Install wl-clipboard:
```
sudo dnf install wl-clipboard
```
Verify wl-paste works independently:
```
echo test | wl-copy
wl-paste
```
The output should be test.
Configure Vim to use the Wayland clipboard:
```
set clipboard=unnamedplus
```
Restart Vim and test: yank a line, then run wl-paste. The line should appear.

Once these steps succeed, the clipboard integration is restored.

Limitations & Caveats

Some terminal emulators block Vim’s clipboard commands unless explicitly enabled.
Wayland compositors may require XWayland to support X11 helpers; otherwise, stick to wl-clipboard.
Remote clipboard forwarding over SSH is limited to X11; for Wayland, consider ssh -Y with a compatible tool.
Re‑compiling Vim may affect other features; back up your configuration first.

Final Checklist

1. :echo has('clipboard') == 1
2. which xclip/xsel/wl-clipboard
3. echo $DISPLAY (for X11)
4. :set clipboard=unnamedplus
5. tmux set-option -g set-clipboard on (if using tmux)
6. ssh -X (if remote)

Follow these steps in order, and you’ll resolve most Vim clipboard integration issues on Linux.

Diagnosing Vim Clipboard Failures on Linux: A Step‑by‑Step Guide