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 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 only works dependably on macOS today.

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 (open issue #26679, Feb 2026). On WSL it fails because Windows ships clipboard images as BMP and Claude Code does not accept BMP.
• 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 Claude Opus 4.7, 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.

1. Drag and drop the image file from Finder, Explorer, or your desktop into the Claude Code terminal window. Works on every platform.
2. Reference a file path directly in your prompt, for example: Analyze this image: /Users/me/Desktop/error.png. Works on every platform.
3. 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, WSL setups, or any environment where clipboard handling is unreliable. Clipboard paste is the fastest for fresh screenshots, but only on Mac. If you are on Windows or WSL and trying to send a screenshot you just took with Win+Shift+S, save it to disk first, then drag or path it in.

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, 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). 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.

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	Silently fails (BMP)	Unreliable on xterm, some gnome-terminal configs
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 here 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 as of February 2026.

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.

Some blog posts mention Alt+V as a Windows fix introduced in Claude Code v1.0.93. We have not been able to confirm Alt+V works in current builds, and the Anthropic-side feature request for native paste is still open, which suggests it does not. Try it if you want, but do not count on it. Drag-and-drop or path is the dependable answer.

Windows With WSL

WSL is where Claude Code image pasting breaks most often. The root cause, documented in GitHub issue #25935, is straightforward: Windows copies images to the clipboard as BMP, WSLg forwards that BMP unchanged through the Wayland clipboard, and Claude Code does not accept BMP. The paste does not error, it just silently does nothing.

You have three workable fixes:

• 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.png inside 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. If you run it from a plain WSL terminal, the file-path method is your best bet.

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 subscriptions table 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 Windows or WSL trying to paste a raw clipboard screenshot? That does not work today, regardless of shortcut. Save the file and drag it in, or paste the path. Skip the rest of this list.

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. 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. 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, but only Mac users can count on it today. Windows and WSL users 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.

FAQ