Claude Code can see images. Copy a screenshot and press Ctrl+V in the prompt (Cmd+V in iTerm2, Alt+V on Windows and WSL), drag an image file into the terminal window, or give Claude a path such as /path/to/screenshot.png. PNG, JPEG, GIF and WebP all work, and Claude Code resizes large images before sending them.
This guide covers each way to add an image, the documented formats and size limits, how images work in VS Code and the desktop app, useful prompts, how images affect your context window, and fixes for image errors. It's based on Anthropic's common workflows page, interactive mode reference and error reference, read on 26 October 2026.
How do you add an image to Claude Code?
Anthropic's docs list three methods:
- Paste from the clipboard. Copy an image, then press the paste shortcut for your terminal in the Claude Code prompt.
- Drag and drop. Drag an image file into the Claude Code window.
- Give a path. Type something like "Analyze this image: /path/to/your/image.png" and Claude reads the file.
The paste shortcut depends on where you run Claude Code:
| Where | Shortcut |
|---|---|
| Most terminals | Ctrl+V |
| iTerm2 on macOS | Cmd+V (or Ctrl+V) |
| Windows | Alt+V |
| WSL | Ctrl+V or Alt+V; use Alt+V if your terminal intercepts Ctrl+V |
Pasting inserts an [Image #N] chip at the cursor, so you can reference images by position: "Compare [Image #1] with [Image #2] and list the layout differences." The action behind the shortcut is chat:imagePaste, which you can rebind in your keybindings file. The Claude Code keyboard shortcuts guide lists the rest.
When Claude refers to an image in its reply, Cmd+Click (Mac) or Ctrl+Click (Windows and Linux) the [Image #1] link to open it in your default viewer.
Which image formats does Claude Code support?
The tools reference says the Read tool returns PNG, JPEG, GIF and WebP files "as visual content that Claude can see, not as raw bytes." A few cases need care:
- HEIC and other binary formats. Read refuses files whose extension it treats as binary, and
.heicis one of the examples. Convert iPhone photos to PNG or JPEG first. - CMYK JPEGs. Claude Code can't decode them. If one is too large to send, re-save it as an RGB PNG or JPEG.
- Animated WebP. If Claude Code can't decode the first frame of a large animated WebP, save that frame as a PNG or JPEG.
- PDFs aren't images but are supported separately: Claude reads short PDFs whole and longer ones in page ranges, up to 20 pages at a time.
If an image fails to resize with a message asking you to convert it, convert to PNG, JPEG, GIF or WebP. Claude Code can check dimensions for those four formats from the file header without decoding the whole image.
What are the size limits for images?
Claude Code resizes and recompresses large images to fit the model's limits before sending them, so Claude may see a downscaled version of a big screenshot. The documented limits are:
| Limit | Value | Source |
|---|---|---|
| Longest edge, single image | 8000 pixels | Error reference |
| Longest edge, more than 20 images in context | 3000 pixels | Error reference |
| Image file the Read tool will open | 128 MB | Tools reference |
| Whole API request | 32 MB | Error reference |
Some Unable to resize image error messages also name a 2000x2000 px limit, for example when an image is over that size and Claude Code's image processing failed, or when it couldn't verify the image's dimensions. The error reference shows that figure only inside these messages, not as a general limit. If you see one, resize the image yourself and attach it again.
Because of downscaling, fine pixel detail in a full-screen capture can get lost. The docs suggest asking Claude to crop the region you care about, for example with ImageMagick through Bash, and then read the crop. Taking a tighter screenshot in the first place works too.
How do images work in VS Code and the desktop app?
- VS Code extension: paste an image from your clipboard into the chat panel's prompt box. To attach other files, hold Shift while dragging them in. Click the X on an attachment to remove it. See the VS Code docs and the Claude Code VS Code guide.
- Desktop app: attach images, PDFs and other files from the + button next to the prompt box, or drag files into the prompt. In a WSL session, the menu may show Add image only, meaning you can attach images but not other files.
- Terminal in an editor: when Claude Code runs as the CLI in an integrated terminal, the terminal shortcuts above apply.
What can you do with images in Claude Code?
The docs suggest prompts like these, and they're a good starting point:
What does this image show?
Describe the UI elements in this screenshot
Here's a screenshot of the error. What's causing it?
This is our current database schema. How should we modify it for the new feature?
Generate CSS to match this design mockup
What HTML structure would recreate this component?
The strongest use is giving Claude something to check its work against. Anthropic's best practices give this example for UI work: "[paste screenshot] implement this design. take a screenshot of the result and compare it to the original. list differences and fix them." For Claude to take that second screenshot itself, it needs a browser, which the Claude Code Chrome guide covers. The Claude Code for frontend guide has more design-to-code workflows.
Other documented tips: use images when a text description would be unclear, include screenshots of errors, UI designs or diagrams, and know that you can use several images in one conversation.
How do images affect your context window?
Every image you add stays in the conversation and is sent again with later requests until it is summarized away. In a long, image-heavy session that can push you into errors such as:
Request too large (max 32MB). Accumulated images and attachments in the conversation pushed the request over the limit. Run /compact, or double press esc to go back and remove attachments.
Running /compact drops accumulated images and attachments, according to the error reference. Pressing Esc twice opens the rewind menu so you can step back past the turn that added a large image. When you're done with a visual task and moving on, /clear starts fresh. The Claude Code compact guide explains when to use each.
If you send a prompt with images and want it back, press Up: Claude Code keeps the ten most recent cleared drafts for the session, including pasted images (v2.1.292 or later).
How do you fix Claude Code image errors?
| Error | What to do |
|---|---|
Image was too large |
Resize below 8000 pixels on the longest edge (3000 with more than 20 images), or take a tighter screenshot |
an image in the conversation could not be processed and was removed |
The API refused an image; if it repeats, update Claude Code |
Unable to resize image |
Convert to PNG, JPEG, GIF or WebP, or resize to the limit the message names |
Request too large (max 32MB) |
Run /compact, or press Esc twice to remove the turn with the attachments |
Request rejected as unprocessable by the model |
Remove images by rewinding with Esc twice, or run /clear |
File is too large to read as an image (the limit is 128MB) |
Export a smaller copy and point Claude at that |
| Ctrl+V does nothing on Windows | Use Alt+V |
Several repeating image errors were fixed in recent releases, for example images attached in VS Code while Claude was working not being resized before v2.1.299. If one keeps coming back, update first; see the Claude Code update guide.
How do you reuse image prompts?
If you find a screenshot prompt that works, such as a design-comparison checklist, it's worth saving so you don't retype it. Kipt keeps prompts as Markdown in a private GitHub repo you own, with blanks like {{component:header}} you fill in each time. Paste the screenshot into Claude Code, then paste the prompt beside it.