How to Paste a Screenshot Into Claude Code and Other Terminal AI Tools

You take a screenshot, switch to your terminal, press Cmd+V, and either nothing happens or a file path shows up instead of the picture. That is expected behavior, not a bug on your machine. A terminal window is built for text, so it has no way to carry image data. Terminal AI tools such as Claude Code get around this by reading the clipboard themselves, but only when you press the right key, on a system where they can reach the clipboard, with an image actually on it.

This guide gives the keys from Anthropic's own documentation, a quick way to check the clipboard, the failure causes in the order worth checking them, and fallbacks that work without the clipboard at all. Keys and behavior can change between versions, so the sources are linked at the end.

Why Cmd+V Does Nothing in a Terminal

When you paste into a terminal, the terminal program sends your text to the app running inside it, character by character. There is no channel in that stream for pixels. So an image-aware command line tool does not wait for the terminal to hand it a picture. Instead, you press a dedicated key, the tool receives that keypress, and then the tool itself asks your operating system what is on the clipboard and attaches the image if it finds one.

That means three things have to line up, and every failure comes from one of them:

1. The right key reaches the tool. If your terminal grabs the keypress first, as many do for Ctrl+V, the tool never sees it.
2. The tool can read your clipboard. This is where Linux, WSL, and remote sessions run into trouble.
3. The clipboard really holds an image. A copied file or a copied path is not an image, even though it looks like one when you copy it.

The Right Key for Claude Code, by System

Anthropic's interactive mode reference lists the image paste shortcut as Ctrl+V, or Cmd+V in iTerm2, or Alt+V on Windows and WSL. In practice that works out to:

When it works, Claude Code inserts an [Image #1] marker at the cursor, so you can refer to the picture by position in your prompt, for example "compare [Image #1] with [Image #2]". You can add several images to one conversation. Cmd+click (Mac) or Ctrl+click (Windows and Linux) on a marker opens the image in your default viewer, which is a quick way to confirm that the right screenshot went in.

Step Zero: Check That the Clipboard Holds an Image

Before you debug the tool, check the clipboard. On a Mac, run this in Terminal right after you copy or capture something:

osascript -e 'clipboard info'

If an image is there, the output lists image types such as «class PNGf» and TIFF picture. If you only see alias or text types like «class utf8», the clipboard holds a file reference or text, and no key will turn that into a pasted image. The companion guide Can't Paste an Image? Check What Is Actually on Your Clipboard shows real output for each case and the equivalent checks for Windows and Linux.

A browser check works on any system: open PasteDownloadApp and press Ctrl+V or Cmd+V. If the preview appears, the browser can see an image on your clipboard, so the problem is between the clipboard and your terminal tool.

When the Key Does Nothing: Causes in Order

1. Wrong key for your system

The most common one. Cmd+V on a Mac Terminal pastes text only. Ctrl+V on Windows is the terminal's text paste. Use the table above.

2. Your terminal intercepts the key

Some terminals treat Ctrl+V as paste and never pass it on. The documentation's own advice for WSL is to try Alt+V. If a key seems to do nothing, try the other one before anything else. If you use a multiplexer such as tmux, test outside it once to rule it out.

3. The clipboard holds a file, not an image

Copying an image file in Finder or File Explorer puts a reference to the file on the clipboard, not its pixels. On macOS 26.4.1, clipboard info printed just alias, 380 in that case, and asking for PNG data from it failed. The fix is to open the image in Preview or your photo viewer and copy it from there, or skip the clipboard and drag the file in (see fallbacks below).

4. Something replaced the image

The clipboard holds one copy action at a time. If you copied a line of text after the screenshot, the screenshot is gone. On a Mac, a screenshot taken with the plain Cmd+Shift+4 shortcut saves a file and puts nothing on the clipboard at all. Adding Control sends it to the clipboard instead. The Windows equivalent is Win+Shift+S, which copies the capture to the clipboard.

5. Linux: the tool cannot reach your clipboard

Linux has no single clipboard interface. X11 and Wayland differ, and command line tools usually read the clipboard through a helper program, xclip on X11 or wl-paste from the wl-clipboard package on Wayland. If the helper is missing, or you are on a Wayland session while a tool talks to X11, there is nothing for it to read. You can check what your session sees:

xclip -selection clipboard -t TARGETS -o      # X11
wl-paste --list-types                         # Wayland

If image/png is in the list, the clipboard is fine and the problem is in the tool or its environment. The official pages I checked do not list Linux prerequisites, so treat this as troubleshooting that users report rather than a documented requirement. A representative example is the Ubuntu image paste bug report.

6. WSL: Windows has the image, Linux cannot see it

In WSL the screenshot lives on the Windows clipboard, while your tool runs on the Linux side. Users report that the Linux-side clipboard tools do not receive image data from Windows by default. That is why the docs bind both keys under WSL: try Alt+V first, and if it still fails, save the screenshot as a file inside a folder that WSL can reach and use the path method below.

7. SSH, containers, and remote sessions

A tool can only read the clipboard of the machine it runs on. If you SSH into a server and start the tool there, it looks at the server's clipboard, which never received your screenshot. This follows from how clipboards work rather than from any one tool's documentation, and it is why remote sessions need the file route: save the image on your own machine, copy it to the server (for example with scp), and give the tool the path.

Fallbacks That Do Not Need the Clipboard

Anthropic's workflow guide lists three ways to add an image, and two of them skip the clipboard entirely:

• Drag and drop the image file into the Claude Code window.
• Give a path in your prompt, for example Analyze this image: /path/to/your/image.png. Most terminals insert a file's path when you drop the file on them, which saves typing it.

These work over SSH, in WSL, and on Linux setups where clipboard paste is unreliable, as long as the file is on the machine where the tool runs.

Turning a clipboard-only screenshot into a file

If the capture exists only on your clipboard, paste it into PasteDownloadApp and download it. The image is processed in your browser and is not uploaded. For screenshots that contain code or small text, choose PNG, because lossy formats can smear thin strokes. PNG vs JPG vs WebP: Real File Sizes Compared shows the size trade-off if you need smaller files.

Other Terminal AI Tools

The same three-part check applies to any command line assistant. OpenAI's Codex CLI documentation says you can paste images into its interactive composer or pass them on the command line, for example codex -i screenshot.png "Explain this error", and that second form is the dependable one over SSH. For other tools, look up the image or paste entry in their keyboard shortcut reference and confirm in your own version, since several tools list a paste key without saying whether it handles images.

Quick Reference

Sources

• Claude Code: Interactive mode, general controls (image paste keys, checked October 18, 2026)
• Claude Code: Common workflows, Work with images
• Codex CLI features
• Claude Code issue: macOS Cmd+V and drag and drop not pasting images, which matches the Ctrl+V guidance above

Frequently Asked Questions

Why can't I paste an image into Claude Code with Cmd+V?

On a Mac, most terminals treat Cmd+V as a text paste, which cannot carry image data. Claude Code listens for Ctrl+V instead (Cmd+V works in iTerm2). On Windows and WSL the key is Alt+V.

What is the shortcut to paste an image in Claude Code on Windows?

Alt+V on Windows and WSL. Under WSL both Ctrl+V and Alt+V are bound, and the documentation suggests Alt+V if your terminal intercepts Ctrl+V.

How do I add an image if paste does not work at all?

Drag the image file into the window, or type its path in your prompt, for example Analyze this image: /path/to/your/image.png. Neither method uses the clipboard.

Why does image paste fail over SSH?

The tool reads the clipboard of the machine it runs on. Over SSH that is the remote server, which never received your screenshot. Save the image locally, copy it to the server, and give the tool the file path.

Related Guides

Where Do Screenshots Go on Windows, Android, and iPhone? Screenshots and copied images do not behave like normal files until you save them. Here is where they go on Windows, Android, and iPhone. Why "Access Clipboard" Fails, and How to Fix It Clipboard read permission errors explained: browser support, HTTPS requirements, and permission prompts. PNG vs JPG vs WebP: Real File Sizes Compared PNG vs JPG vs WebP for quality, transparency, and file size, backed by real measured results, not general claims.