Claude Code can read images. Drop a screenshot in, paste a UI mockup, or hand it a chart, and Claude will analyze it the same way it analyzes code. The catch is that pasting works reliably on macOS but silently fails on Windows and WSL, which is what sends most people to Google.
This guide covers every official way to give Claude Code images, where each method actually works, the four image formats Claude Code accepts, and the example prompts that turn a screenshot into working code. The short answer if you want to skip the troubleshooting: drag and drop a file or paste a file path in your prompt. Both work on every platform. Clipboard paste is most dependable on macOS, and as of Claude Code v2.1.157 (May 2026) WSL finally got a working paste shortcut too.
The Key Takeaways
- Three official methods to add images to Claude Code: drag and drop, copy and paste, or pass a file path in your prompt.
- Drag and drop and file paths work on every platform. Use these if you want a method that never fails.
- Clipboard paste with Ctrl+V works reliably only on macOS. On Windows native, raw clipboard images from Snipping Tool silently fail (issue #26679, still open as of June 2026). On WSL, clipboard paste used to fail because Windows ships images as BMP, but v2.1.157 (May 29, 2026) fixed it with a dedicated Alt+V keybinding.
- Use Ctrl+V, never Cmd+V, even on Mac, where Cmd+V is captured by the terminal before Claude Code sees it.
- Supported formats: JPEG, PNG, GIF, WebP. Max 5 MB per image locally, up to 100 images per request.
Can Claude Code See Images?
Yes. Claude Code uses the same multimodal vision capability as the rest of the Claude family, including the latest Claude Opus 4.8, so it can read screenshots, diagrams, charts, mockups, and any other still image you hand it. The CLI just adds the input layer that lets you get the file there.
Vision is one of the reasons Claude Code is more useful than older code-only assistants. Show Claude Code a Figma export and it will write the matching HTML and CSS. Show it a stack trace screenshot and it will trace the bug back to the file. If you show it a database schema diagram and it will draft 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.
How to Add Images to Claude Code: 3 Methods
According to the official Anthropic documentation, there are exactly three supported ways to add an image to Claude Code. The docs treat all three as equal, but in practice their reliability is anything but.
- Drag and drop the image file from Finder, Explorer, or your desktop into the Claude Code terminal window. Works on every platform.
- Reference a file path directly in your prompt, for example:
Analyze this image: /Users/me/Desktop/error.png. Works on every platform. - Copy and paste the image with Ctrl+V (not Cmd+V). Works reliably only on macOS. On Windows and WSL, raw clipboard images silently fail.
Pick by what you have on hand. Drag and drop is fastest when the file already exists on disk. File paths are the right call for scripts or any environment where clipboard handling is unreliable. Clipboard paste is the fastest for fresh screenshots; use Ctrl+V on Mac and Alt+V on WSL (added in v2.1.157, May 2026). If you are on Windows native and trying to send a screenshot you just took with Win+Shift+S, save it to disk first, then drag or path it in, because raw clipboard paste still does not land there.
Method 1: Drag and Drop
Open the folder where your image lives, click and hold the file, then drag it onto the Claude Code terminal. Drop, and Claude Code attaches the image and waits for your prompt.
If the file opens in a new tab instead of attaching to Claude Code, hold Shift while you drag to force the terminal to treat the drop as a file reference rather than launching the system handler. This matters most in iTerm2, Windows Terminal, and Warp, where default drag behavior is application-dependent.
Drag and drop works reliably on macOS and Windows native. On Linux it depends on your desktop environment and terminal emulator. On WSL, it works only when you drag from a path the Linux side can see, like /mnt/c/Users/..., not from a Windows-only path.
Method 2: Paste With Ctrl+V (macOS Only, Reliably)
This method is reliable on macOS and unreliable everywhere else. Use it on Mac, fall back to drag and drop or file paths on Windows and WSL.
On Mac, Cmd+Ctrl+Shift+4 captures a screen region directly to the clipboard, plain Cmd+Shift+4 saves it to your desktop instead. Then press Ctrl+V inside Claude Code. Claude Code will show a placeholder like [Image #1] in the prompt and attach the image when you submit. Type your question after the placeholder and press Enter.
The single biggest mistake Mac users make: pressing Cmd+V. Cmd+V is captured by the terminal app itself, not by Claude Code, so the image never reaches the CLI. Use Ctrl+V.
On Windows native, Win+Shift+S copies your screenshot to the clipboard, but pasting it into Claude Code with Ctrl+V silently does nothing. This is a documented limitation tracked in GitHub feature request #26679 (filed February 2026, still open as of June 2026). Save the screenshot to disk and drag it in, or paste the path. The one paste pattern that does work on Windows: copy a saved image file in File Explorer with Ctrl+C, then paste with Ctrl+V. Claude Code reads the file reference, not the raw bitmap. If you run Claude Code under WSL rather than native Windows, you have a better option now, covered in the WSL section below.
On Linux, clipboard image paste works on some terminals (Konsole, Kitty, Alacritty) and fails on others (xterm, gnome-terminal in some configs). Treat it as opportunistic, not dependable.
Method 3: File Path in Your Prompt
The most boring method, and the only one that works everywhere. 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 to the message before sending. Both absolute and relative paths work. On WSL, convert Windows paths from C:\Users\me\file.png to /mnt/c/Users/me/file.png.
The cleanest workflow is to drop the image straight into the project folder you are working in, then reference it by its relative path. Save your screenshot to something like ./screenshots/bug.png inside the repo, then prompt Claude with Look at ./screenshots/bug.png and tell me what's broken. Claude Code reads it from disk like any other file in your project, so this works on every OS and in every terminal, including WSL where clipboard paste is broken. It is also the easiest pattern to keep tidy across long sessions, because the image lives next to the code Claude is editing and you can git-ignore the folder.
This method is also the only way to send images programmatically, for example from a script that pipes prompts into the CLI with claude -p.
Method × Operating System Reliability
| Method | macOS | Windows native | WSL | Linux |
|---|---|---|---|---|
| Drag and drop a file | Reliable | Reliable | Partial (use /mnt/c/...) | Depends on terminal |
| File path in prompt | Reliable | Reliable | Reliable | Reliable |
| Ctrl+V paste raw clipboard image | Reliable | Silently fails (#26679 open) | Use Alt+V instead | Unreliable on xterm, some gnome-terminal configs |
| Alt+V paste raw clipboard image | n/a (use Ctrl+V) | Not for native paste | Reliable (v2.1.157+) | n/a |
| Ctrl+V paste a copied file (Ctrl+C in Explorer) | Works | Works | Works if path is /mnt/c/... | Works |
If you want one method that always works, no matter what terminal or OS you are on, use file paths. Drag and drop is a close second. Clipboard paste of raw images is a Mac-only convenience right now.
How to Add Images to Claude Code on Each OS
Each operating system has its own quirks. Here is what actually works on each.
macOS
The good platform. Use Ctrl+V to paste raw clipboard images, never Cmd+V. To grab a screenshot directly to the clipboard, press Cmd+Ctrl+Shift+4 and select the area. Plain Cmd+Shift+4 saves to disk instead, which is the wrong move if you want to paste.
iTerm2, Warp, WezTerm, and the default macOS Terminal all behave the same way for Claude Code paste. The terminal app sees Cmd+V and runs its own paste-buffer logic, which only handles text, not images, so the image is dropped before Claude Code ever gets a chance to read it. Switching to Ctrl+V solves it.
Drag and drop from Finder and file paths in your prompt also work, of course.
Windows Native (PowerShell, Windows Terminal, Command Prompt)
Clipboard paste of a raw screenshot does not work on native Windows today. Win+Shift+S puts the image on the clipboard, but Claude Code’s Ctrl+V handler does not pick it up. This is tracked in open feature request #26679, still open as of June 2026. Note this applies to native Windows (PowerShell, Windows Terminal, Command Prompt). If you run Claude Code through WSL, the May 2026 Alt+V fix applies instead, see the next section.
Use one of these instead:
- Drag and drop the screenshot file from File Explorer into the Claude Code window. Hold Shift while dragging if the file launches in another app instead of attaching.
- Save and path it. Use Win+Shift+S, save the screenshot to a folder, then reference its path in your prompt:
Analyze this: C:\Users\you\Pictures\shot.png. - Copy the file, not the image. In File Explorer, select the saved screenshot file and press Ctrl+C, then Ctrl+V inside Claude Code. Claude Code reads the file reference and attaches the image. This works because it bypasses the raw-bitmap clipboard path entirely.
Anthropic did ship an official Alt+V image-paste keybinding in v2.1.157 (May 29, 2026), but the changelog scopes that fix to WSL and screenshot paste on Windows 11, not to raw clipboard paste on native PowerShell or Command Prompt, where #26679 remains open. If you are on native Windows, treat drag-and-drop or a file path as the dependable answer and use Alt+V only once you are running under WSL.
Windows With WSL
WSL used to be where Claude Code image pasting broke most often, and that changed in late May 2026. The root cause, documented in GitHub issue #25935, was straightforward: Windows copies images to the clipboard as BMP, WSLg forwards that BMP unchanged through the Wayland clipboard, and older Claude Code builds did not accept BMP, so the paste silently did nothing.
The fix landed in v2.1.157 (May 29, 2026), which the changelog describes as “fixed image paste (alt+v keybinding), screenshot paste on Windows 11, and added support for dragging images from Windows Explorer.” So on a current build, the fastest path is to copy your screenshot to the clipboard and press Alt+V inside Claude Code, not Ctrl+V. Make sure you are on the latest version first with claude update, since this only works on v2.1.157 and newer.
If you are stuck on an older build or Alt+V still misbehaves on your setup, you have three reliable fallbacks:
- Use a file path as in Method 3. Save your screenshot to
C:\Users\me\Pictures\shot.png, then reference it as/mnt/c/Users/me/Pictures/shot.pnginside Claude Code. - Convert clipboard via PowerShell, which lets you save the Windows clipboard image to a PNG file you can then pass to Claude Code:
powershell.exe -Command "(Get-Clipboard -Format Image).Save('shot.png')". - Install the Claude Code Image Paste (WSL) VS Code extension, a community extension that grabs the Windows clipboard, converts the image to PNG, saves it to your project, and pastes the path into the Claude Code terminal automatically.
If you run Claude Code through Cursor or VS Code’s integrated terminal, the extension is the smoothest fix on older builds. From a plain WSL terminal on a current build, Alt+V is now the quickest route, with the file-path method as your reliable backup. Curious about Cursor plans? Our Cursor pricing breakdown covers every tier.
Linux
On most modern terminals (Konsole, modern GNOME Terminal, Kitty, Alacritty), Ctrl+V paste of a clipboard image works. On older or minimal terminals like xterm, urxvt, or Linux frame buffers, image pasting will not work at all and you should fall back to file paths.
Your screenshot tool needs to copy the image to the clipboard, not just save it as a file. GNOME Screenshot has the option, Flameshot has a “copy to clipboard” button, and KDE’s Spectacle has the same.
Supported Image Formats and Limits
Claude Code accepts the four standard web formats and rejects everything else. Knowing which format to send saves you the silent-fail debugging loop where Claude Code seems to ignore your image because it could not parse it in the first place.
| Format | Best for | Notes |
|---|---|---|
| PNG | Screenshots, UI mockups, diagrams, anything with text | Lossless, crisp text rendering, recommended default for development work |
| JPEG | Photographs, real-world images | Smaller than PNG for photos, but blurs text edges |
| WebP | Anything you want compressed without losing quality | Smallest files at equivalent quality, fully supported |
| GIF | Animations and screen recordings | Claude Code analyzes only the first frame |
Not supported: BMP, TIFF, SVG. If you paste any of these, the image is silently dropped. Convert to PNG first.
Hard limits to keep in mind:
- 5 MB per image in Claude Code locally
- 8000 x 8000 pixels maximum resolution per image
- 100 images per request maximum
- If you send more than 20 images at once, each is capped at 2000 x 2000 pixels
A 1000 x 1000 pixel image costs roughly 1334 tokens of context. That is cheap enough to use freely, but ten full-resolution screenshots in one prompt will eat real context.
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 stack trace screenshot or error toast directly. 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]”
OCR from screenshots. Pull text out of an image without manually retyping. Useful for terminal output you cannot copy from.
“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 architecture sketch and ask for migrations or critique.
“Here’s our current Postgres schema. Add a
subscriptionstable with the right foreign keys: [Image #1]”
For long-running multi-image sessions, consider Claude Code skills you can build yourself that automate the screenshot-paste-prompt loop.
Troubleshooting: Image Paste Not Working
If your image will not attach, run through this checklist in order. Most failures are one of these things.
Platform check. Are you on native Windows trying to paste a raw clipboard screenshot with Ctrl+V? That still does not work today (#26679). Save the file and drag it in, or paste the path. On WSL, raw paste does work now, but only with Alt+V on v2.1.157 or newer, so run claude update before assuming it is broken.
Format check. Is your file a JPEG, PNG, GIF, or WebP? If it is BMP, TIFF, or SVG, convert it first. Right-click in Preview (Mac) or Paint (Windows) and Save As PNG.
Shortcut check. On Mac, are you using Ctrl+V, not Cmd+V? Cmd+V is captured by the terminal before Claude Code sees it.
Clipboard check. Is there actually an image on the clipboard, or just a file reference? On Mac, Cmd+Shift+4 (without Ctrl) saves to disk. Use Cmd+Ctrl+Shift+4 to copy directly to clipboard.
Update check. Run claude --version and claude update. Image-handling behavior has changed across releases, and WSL paste in particular only works on v2.1.157 (May 29, 2026) or newer. If you hit a session-breaking bug, restart Claude Code.
Fallback. If nothing else works, drag the file in or paste a file path. These methods bypass every clipboard layer that can fail.
If you are also dealing with auth pain 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 referenced image in your default image viewer. Fast way to verify Claude is looking at the right thing in a multi-image session.
Skip the CLI Headaches: Use Fello AI on Mac Instead
If you are reading this guide because the clipboard quirks and WSL workarounds are wearing you down, there is a faster path. Fello AI is a native Mac app that gives you Claude with image upload that just works. No Cmd+V vs Ctrl+V games, no BMP conversion scripts, no save-the-file-then-drag dance. 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. One subscription, every major model, including DeepSeek which most chat apps still skip. The same screenshot you would have spent ten minutes routing into Claude Code through a workaround takes two seconds here, and you can run the same image through Claude, ChatGPT, and Gemini back to back to compare answers without paying three separate subscriptions. For a side-by-side on Claude Code’s own plans, see our Claude Code pricing guide. The app holds a 4.7-star rating across 25,000+ reviews.
Image handling behaves the way you would expect from a real desktop app. Drag from Finder, paste with Cmd+V, or click the attach button. The image goes straight to whichever model you have selected, with the same Claude vision capability you get in the CLI, minus every workaround in this guide. For Mac users who want Claude’s image reasoning without fighting the terminal, this is the cleanest option.
Conclusion
Three official methods, but only two of them work reliably across every platform: drag and drop a file, or paste a file path in your prompt. Clipboard paste is real too: Mac users press Ctrl+V, and WSL users now press Alt+V on v2.1.157 or newer. Native Windows is the lone holdout, so there you should save the screenshot to disk first.
For everyone sticking with the CLI, bookmark this guide for the next time a paste silently swallows your screenshot. The drag-and-drop and file-path methods will get you out of every clipboard mess Claude Code can throw at you. And if you are still deciding whether the CLI is worth paying for, our guide on Claude Code’s free and paid options lays out every path.
FAQ
Why doesn’t Cmd+V paste images in Claude Code on Mac?
Because the macOS terminal app captures Cmd+V before Claude Code sees it, and the terminal’s paste handler only knows how to paste text. Use Ctrl+V instead.
How do I paste images into Claude Code on Windows?
On native Windows you mostly cannot, today. Raw clipboard images from Snipping Tool silently fail to attach via Ctrl+V (#26679 is still open). Save the screenshot to disk and drag it in, or paste the file path. You can also copy a saved image file in File Explorer with Ctrl+C and paste with Ctrl+V, since Claude Code reads the file reference. If you run Claude Code under WSL instead, raw paste does work as of v2.1.157 (May 2026) using Alt+V.
Why is image paste not working in WSL?
It used to fail because Windows copies clipboard images as BMP and older Claude Code builds did not accept BMP. Version 2.1.157 (May 29, 2026) fixed it, so on a current build you paste with Alt+V, not Ctrl+V. Run claude update first. If it still misbehaves, fall back to a file path under /mnt/c/..., the PowerShell clipboard-to-PNG trick, or the Claude Code Image Paste (WSL) VS Code extension.
What image formats does Claude Code support?
JPEG, PNG, GIF, and WebP. BMP, TIFF, and SVG are not supported. PNG is the best default for screenshots and any image with text, JPEG for photos, WebP for the smallest files at the same quality.
How many images can I send in one Claude Code prompt?
Up to 100 images per request, with a 5 MB per-image cap and 8000 x 8000 pixel max resolution. If you include more than 20 images at once, each is downsampled to 2000 x 2000 pixels.
