When Claude Code won't paste images on Linux (Wayland)

I tried pasting a screenshot into Claude Code with Ctrl+V and nothing happened. The image was clearly on my clipboard, but the prompt just sat there. The culprit turned out to be the clipboard utility.

The cause

On Linux, Claude Code needs an external clipboard utility to read the system clipboard, and it has to match your display server.

• Wayland: wl-clipboard (wl-copy / wl-paste)
• X11: xclip or xsel

So I checked my session type and what was actually installed:

echo $XDG_SESSION_TYPE   # wayland
command -v wl-copy       # nothing
command -v xclip         # /usr/bin/xclip

There it was. I was on Wayland but only had the X11 tool (xclip) installed. Text still pasted fine because it goes through XWayland, but images copied by a native Wayland app (a screenshot tool, in my case) land on the Wayland clipboard, and xclip can’t read those. That’s why only images were failing.

The fix

Install the Wayland clipboard tool:

sudo apt-get install -y wl-clipboard

On Fedora it’s dnf install wl-clipboard, on Arch pacman -S wl-clipboard.

That’s not the whole story, though. Claude Code only detects the clipboard tool once, at startup. If you install it while a session is already running, that session will keep behaving as if the tool isn’t there. You have to restart Claude Code.

# quit with /exit or Ctrl+C twice, then
claude
# use claude --continue to pick up where you left off

Restart, paste your image, and the [Image #1] chip shows up in the prompt.

Codex works the same way

Codex (codex-cli) reads the clipboard the same way. Install wl-clipboard, restart, and Ctrl+V drops images in there too. This isn’t really a tool-specific problem, it’s a Wayland clipboard thing, so most terminal CLIs that deal with clipboard images run into the same wall.

If it still doesn’t work

• Some terminals grab Ctrl+V for themselves. Try Alt+V instead.
• Double-check your session. If echo $XDG_SESSION_TYPE says wayland, you want wl-clipboard; if it says x11, xclip or xsel is the right tool.

Test environment

Item	Version
OS	Kubuntu 26.04 LTS (Resolute Raccoon), kernel 7.0.0-27-generic
Desktop	KDE Plasma (Wayland)
Terminal	Ghostty 1.3.1
Clipboard	wl-clipboard 2.2.1
Claude Code	2.1.172
Codex	codex-cli 0.142.4