Claude Code Images: How to Paste, Upload, and Use Them on Any OS

Claude Code can read images. Drop a screenshot in, paste a UI mockup, or hand it a chart, and Claude analyzes it the same way it analyzes code. Pasting used to be the weak spot, and Windows was where it broke. That has changed: Alt+V now pastes images on Windows and WSL, Ctrl+V does it on macOS and Linux, and iTerm2 accepts Cmd+V as well.

This guide covers the three official ways to give Claude Code an image, the right paste shortcut for every platform, screenshots (including letting Claude take its own), SSH, the VS Code extension and the desktop app, the formats and limits, and why Claude Code cannot generate images. Every claim is checked against Anthropic’s documentation and the Claude Code changelog at version 2.1.292 (October 2026).

The Key Takeaways

• Three official methods to add images to Claude Code: drag and drop, paste from the clipboard, or put a file path in your prompt.
• The paste shortcut depends on the platform: Ctrl+V on macOS and Linux, Cmd+V also works in iTerm2, and Alt+V on Windows and WSL.
• Native Windows paste works now. The feature request for it (issue #26679) was closed as completed on 17 August 2026. If Alt+V says no image was found, run claude update.
• Over SSH, paste cannot work, because the clipboard stays on your own computer. Copy the file to the server with scp and give Claude the path.
• Claude reads JPEG, PNG, GIF and WebP. Claude Code converts some other formats for you and shrinks pasted images to 2,000 pixels on the long side.
• Claude Code cannot generate images. It can write SVG or HTML, or call an image model through a script or an MCP server.

Can Claude Code See Images?

Yes. Claude Code runs on the same models as the rest of the Claude family, including Claude Opus 5.5 and Sonnet 5.5, and all of them read images. Screenshots, diagrams, charts, mockups and photos all work. Claude Code adds the input layer that gets the file to the model, and it saves every pasted image to disk, so Claude can also open it as a file and copy it into your project.

Vision is one of the reasons Claude Code is more useful than older code-only assistants. Show it a Figma export and it writes the matching HTML and CSS. Show it a screenshot of a stack trace and it traces the bug back to the file. Show it a database schema diagram and it drafts the migration.

Combined with the best Claude Code skills, images turn the CLI into a fast loop for design-to-code work that used to need a back-and-forth chat window. The same loop also works on mobile if you use Claude Code on your phone through Anthropic’s Remote Control feature.

Can Claude Code Generate Images?

No. Anthropic’s vision documentation says Claude “is an image understanding model only” and “cannot generate, produce, edit, manipulate, or create images.” Claude Code runs on those same models, so the answer is the same in the terminal as in the chat app. Our guide to whether Claude can generate images covers the chat side.

What Claude Code can do is write code that produces an image: an SVG icon, an HTML and CSS mockup, a chart from a plotting library, or a canvas script. For diagrams, icons and UI drafts that is often better than a picture, because the result is editable text that lives in your repo.

For photos and illustrations, Claude Code has to call an image model that someone else runs. There are two ways to set that up:

• A script. Ask Claude Code to write and run a small script that calls an image API from OpenAI or Google with your own API key, then saves the result into your project.
• An MCP server. Connect an MCP server that offers an image tool. Since v2.1.283, images returned by MCP tools are also saved to a file, so Claude can move them where your code expects them.

Either way, the image provider bills you separately from your Claude plan.

How to Add Images to Claude Code: 3 Methods

The official Claude Code documentation lists three ways to add an image. All three work on every platform, as long as you use the right shortcut for yours.

1. Drag and drop the image file from Finder, File Explorer or your desktop into the Claude Code window.
2. Paste from the clipboard with Ctrl+V, or with Alt+V on Windows and WSL.
3. Give Claude a file path in your prompt, for example: Analyze this image: /Users/me/Desktop/error.png.

Pick by what you have on hand. Paste is fastest for a screenshot you just took. Drag and drop is fastest when the file already exists. A file path is the right call for scripts, SSH sessions and anything automated, because it never touches the clipboard.

Method 1: Drag and Drop

Open the folder where your image lives, drag the file onto the Claude Code window and drop it. Claude Code attaches the image, notes where it came from, and waits for your prompt. You can drop several images at once.

On WSL, dragging images from Windows File Explorer has worked since v2.1.157 (29 May 2026). On Linux, drag and drop depends on your terminal emulator, so keep the file-path method as your backup there. In the VS Code extension, hold Shift while you drag a file into the prompt box.

Method 2: Paste From the Clipboard

Copy an image, click into the Claude Code prompt and press the paste shortcut. Claude Code inserts an [Image #1] chip at the cursor. The chip sits where you put it in your sentence, so you can write prompts like “make [Image #1] look like [Image #2].” Type the rest of your question and press Enter.

The shortcut is what trips people up, because it changes by platform:

The most common mistake on a Mac is pressing Cmd+V in Terminal or Warp. That key belongs to the terminal app, which pastes text, so the image never reaches Claude Code. iTerm2 is the exception, because Claude Code maps its Cmd+V to Ctrl+V.

If your terminal grabs the shortcut for something else, change it. Run /keybindings to open ~/.claude/keybindings.json and bind another key to the chat:imagePaste action. Claude Code picks up the change without a restart.

Method 3: File Path in Your Prompt

The most boring method, and the one that never depends on a clipboard or a terminal. Type the path to your image into the prompt as part of your message:

Analyze this screenshot and tell me what's wrong: /Users/lenka/Desktop/login-bug.png

Or with a relative path from your project root:

Compare this design to our current /src/components/Header.tsx: ./mockups/header-v2.png

Claude Code reads the file from disk and attaches it. Absolute and relative paths both work. On WSL, a Windows path like C:\Users\me\file.png becomes /mnt/c/Users/me/file.png.

The tidiest workflow is to save screenshots straight into the project, for example ./screenshots/bug.png, then prompt Look at ./screenshots/bug.png and tell me what's broken. The image lives next to the code Claude is editing, and you can git-ignore the folder.

This is also the only way to send images from a script, for example one that pipes prompts into the CLI with claude -p.

Method × Platform at a Glance

If you want one method that works in every setup, use file paths. Paste is the fastest, as long as you press the right key for your platform.

How to Add Images to Claude Code on Each OS

Each operating system has its own screenshot keys and its own quirks. Here is what works on each.

macOS

Press Cmd+Ctrl+Shift+4 and select an area to copy a screenshot straight to the clipboard, or Cmd+Ctrl+Shift+3 for the whole screen. Then press Ctrl+V in Claude Code (or Cmd+V in iTerm2). Plain Cmd+Shift+4, without Ctrl, saves the screenshot to your desktop instead, which is fine if you would rather drag the file in.

macOS puts screenshots on the clipboard in TIFF format, which Claude itself does not read. Claude Code converts it for you, and has since v2.1.0, so you never need to save and re-export first.

Drag and drop from Finder and file paths in your prompt work too, of course.

Windows Native (PowerShell, Windows Terminal, Command Prompt)

Press Win+Shift+S to copy a screenshot to the clipboard, then press Alt+V inside Claude Code. Ctrl+V is the terminal’s text paste on Windows, so it will not attach an image.

Alt+V for Windows was added back in v1.0.93, but it did not always find a fresh screenshot on the clipboard until a fix in v2.1.141. That gap is why so many older guides, including an earlier version of this one, said Windows paste was broken. The GitHub feature request #26679 was closed as completed on 17 August 2026. If Alt+V still reports that no image was found, update with claude update.

You can also skip the clipboard entirely:

• Drag and drop the screenshot file from File Explorer into the Claude Code window.
• Save it and give the path. Save the screenshot from the Snipping Tool, then reference it in your prompt: Analyze this: C:\Users\you\Pictures\shot.png.

Windows With WSL

WSL used to be where image paste broke most often. The cause, documented in GitHub issue #25935, was that Windows copies images to the clipboard as BMP and older Claude Code builds did not accept BMP. That was fixed in v2.1.47 (February 2026). Later releases added a PowerShell fallback for clipboards that xclip and wl-paste cannot read (v2.1.136), and then the Alt+V keybinding, screenshot paste on Windows 11 and drag and drop from File Explorer (v2.1.157, 29 May 2026).

On a current build, copy your screenshot with Win+Shift+S and press Alt+V. Ctrl+V is bound too, but many terminals take Ctrl+V for themselves, so Alt+V is the one to remember. Run claude update first if you are on an old version.

If paste still misbehaves on your setup, you have two reliable fallbacks:

• Use a file path. Save the screenshot to C:\Users\me\Pictures\shot.png, then reference it as /mnt/c/Users/me/Pictures/shot.png.
• Save the clipboard to a PNG with PowerShell, then pass that file to Claude Code: powershell.exe -Command "(Get-Clipboard -Format Image).Save('shot.png')".

If you run Claude Code in the VS Code extension under WSL, pasting a screenshot into the chat box attaches the image since v2.1.267. Before that it could insert raw image bytes instead. One more WSL limit: the Chrome integration that lets Claude take its own browser screenshots (covered below) does not run under WSL. Curious about AI code editors? Our Cursor pricing breakdown covers every tier.

Linux

Claude Code reads the Linux clipboard through xclip on X11 or wl-paste on Wayland. If Ctrl+V says there is no image on the clipboard, install whichever one your session uses (xclip, or the wl-clipboard package) and try again.

Your screenshot tool also has to copy the image to the clipboard, not just save it. GNOME Screenshot has the option, Flameshot has a “copy to clipboard” button, and KDE’s Spectacle has the same. On a minimal terminal or a server with no clipboard at all, use file paths.

Screenshots: Paste Them, or Let Claude Take Its Own

Most of the images people give Claude Code are screenshots. The fastest route on each platform:

• macOS: Cmd+Ctrl+Shift+4, then Ctrl+V (or Cmd+V in iTerm2).
• Windows: Win+Shift+S, then Alt+V.
• WSL: Win+Shift+S, then Alt+V.
• Linux: your screenshot tool’s copy option, then Ctrl+V.

For web work, you often do not need to take the screenshot at all. With the Chrome integration, Claude Code drives Chrome or Edge through the Claude in Chrome extension. It opens your app, reads console errors and takes its own screenshots to check that a UI matches the mockup. Start it with claude --chrome. It needs the extension, a direct Anthropic plan (Pro, Max, Team or Enterprise) and a /login sign-in, and it does not run under WSL. Ask it to “take a screenshot of the checkout page and save it to disk” and it writes the file and tells you the path (that option has worked since v2.1.211).

The Claude Code desktop app does the same inside its Browser pane. Claude starts your dev server, opens the app there, then takes screenshots, inspects the page and fixes what it finds. Browser-automation MCP servers such as Playwright’s are a third option if you want screenshots inside your own test setup.

Claude Code Over SSH and in Remote Sessions

The clipboard lives on the computer in front of you. When Claude Code runs on another machine over SSH, it cannot read that clipboard, so pasting an image will not work. Claude Code tells you so and suggests scp, which is the right fix. Copy the file to the server, then give Claude the path:

scp ~/Desktop/shot.png you@server:~/project/screenshots/

Then prompt Look at ./screenshots/shot.png from the project folder on the server. If you control Claude Code from your phone through Remote Control, images you upload from the mobile app arrive with a saved file path (since v2.1.239), so Claude can copy them into files it creates.

Images in the VS Code Extension and the Desktop App

You do not need a terminal at all. In the VS Code extension, paste an image from your clipboard into the prompt box, or hold Shift and drag a file in. Since v2.1.275 you can send an image without typing any text.

In the Claude Code desktop app, use the + button next to the prompt box, or drag and drop files into the prompt. It takes images, PDFs and other files, which makes it the easiest place to share a bug screenshot or a design mockup. Since v2.1.275, images you paste or attach in Desktop and VS Code are saved where Claude can open them without a permission prompt.

Supported Image Formats and Limits

Claude reads four image formats. Sending the right one saves you the loop where Claude Code seems to ignore your image because it could not use it in the first place.

Other formats are not a dead end any more. Claude Code converts the TIFF that macOS screenshots put on the clipboard and the BMP that Windows hands to WSL, and since v2.1.285 it converts BMP, HEIC, HEIF, AVIF and TIFF files where it can. SVG is different: it is text, so Claude reads an SVG file as code rather than as a picture. If an image still fails to attach, convert it to PNG.

The limits that matter:

• 2,000 pixels: Claude Code shrinks pasted images so the long side is at most 2,000 pixels, so a huge screenshot will not break your session.
• 8000 x 8000 pixels is the most the Claude API accepts for one image.
• 10 MB per image on Anthropic’s own API, and 5 MB if your Claude Code runs through Amazon Bedrock or Google Cloud.
• 100 images per request on models with a 200k-token context window and 600 on the others. Above 20 images in one request, each image must fit within 2,000 x 2,000 pixels.

Claude reads an image in 28 x 28 pixel tiles, and each tile costs one token. A 1000 x 1000 screenshot is 1,296 tokens. A 1920 x 1080 screenshot is about 2,700 tokens on Claude 4.7 and later models, which read images at higher resolution. That is cheap enough to use freely, but a long session full of screenshots does eat context, so run /compact when it gets heavy.

Use Cases: What to Actually Do With Images in Claude Code

The methods are useless without good prompts. These are the four highest-leverage workflows we use daily.

Design-to-code from a mockup. Drop a Figma export or screenshot and ask Claude Code to build it.

“Generate the React component and Tailwind classes that match this design: [Image #1]”

Error screenshot debugging. Paste a screenshot of a stack trace or an error toast. Faster than typing it out.

“Here’s the error I’m seeing in the dev console. What’s causing it and what file should I look at? [Image #1]”

Text from screenshots. Pull text out of an image without retyping it. Useful for output you cannot copy, like a settings panel.

“Extract the configuration values from this screenshot of our prod settings panel into a JSON object: [Image #1]”

Schema and diagram review. Drop a database ER diagram or an architecture sketch and ask for migrations or a critique.

“Here’s our current Postgres schema. Add a subscriptions table with the right foreign keys: [Image #1]”

For long sessions with many images, consider Claude Code skills you build yourself to automate the screenshot, paste and prompt loop.

Troubleshooting: Image Paste Not Working

If your image will not attach, run through this list in order. Most failures are one of these.

Shortcut check. Windows and WSL use Alt+V. macOS uses Ctrl+V, and Cmd+V only in iTerm2. Linux uses Ctrl+V.

Clipboard check. Is there an image on the clipboard, or did the screenshot go to a file? On a Mac, Cmd+Shift+4 without Ctrl saves to disk. Use Cmd+Ctrl+Shift+4 to copy instead.

Version check. Run claude --version and claude update. Windows screenshot paste with Alt+V was fixed in v2.1.141, and the WSL fixes landed between v2.1.47 and v2.1.157.

Linux check. Is xclip (X11) or wl-clipboard (Wayland) installed? Claude Code needs one of them to read the clipboard.

SSH check. Is Claude Code running on a remote machine? Then paste cannot work. Copy the file over with scp and use its path.

Format and size check. If the file is an unusual format, convert it to PNG. If it is too large, Claude Code now names the cause in the error and tells you how to fix it.

Fallback. If nothing else works, drag the file in or paste its path. Both skip every clipboard layer that can fail.

If you are also dealing with sign-in trouble in your terminal, the Claude Code paste auth code fix covers a related family of clipboard issues you might want to handle in the same session.

Pro Tip: Open Images Claude References

When Claude Code mentions images in its replies as [Image #1], [Image #2] and so on, those are clickable. Cmd+Click on macOS or Ctrl+Click on Windows and Linux opens the image in your default viewer. It is a fast way to check that Claude is looking at the right thing in a session with many images.

Skip the CLI Headaches: Use Fello AI on Mac Instead

If you came here because you just want Claude to look at a picture, the terminal is the long way round. Fello AI is a native Mac app that gives you Claude with image upload that just works. No shortcut table, no SSH copies, no format conversions. You drop a screenshot into the chat, ask your question, and Claude answers.

Fello AI bundles Claude, ChatGPT, Gemini, Grok and DeepSeek into one app for $9.99/month. You can run the same screenshot through Claude, ChatGPT and Gemini back to back and compare the answers, without paying for three subscriptions. And unlike Claude Code, it also generates images: switch to an image model in the same chat and turn Claude’s plan into a picture. For Claude Code’s own plans, see our Claude Code pricing guide. The app holds a 4.7-star rating across 27,000+ reviews.

Images work the way you expect in a desktop app. Drag from Finder, paste with Cmd+V, or click the attach button. The image goes to whichever model you have selected, with the same Claude vision you get in the CLI. For Mac users who want Claude’s image reasoning without the terminal, this is the cleanest option.

Conclusion

Claude Code takes images three ways, and in 2026 all three work on every platform: drag and drop a file, paste from the clipboard, or put a file path in your prompt. The only thing to remember is the shortcut: Ctrl+V on macOS and Linux (Cmd+V in iTerm2), Alt+V on Windows and WSL. Over SSH, copy the file across and use its path.

Claude Code reads images but does not make them, so for pictures, wire up an image API or an MCP server, or use an app that has an image model built in. And if you are still deciding whether the CLI is worth paying for, our guide to Claude Code’s free and paid options lays out every path.

FAQ