How to Attach Images in Claude Code: Paste, Drag, or Use a File Path¶

For / Key Points

For: Developers who want to give Claude Code an error screen, UI mockup, chart, or other image

Key Points:

Paste clipboard images with Ctrl+V on macOS/Linux or Alt+V on Windows
Drag an image into the terminal or reference a local file path in the prompt
For size errors, crop irrelevant regions and resize the longest edge to 2,000 pixels

Three attachment methods¶

1. Paste from the clipboard¶

Use this for the error screen or browser page currently in front of you.

macOSWindowsLinux

Capture a region with Cmd+Shift+4 or another screenshot tool
Press Ctrl+V in the Claude Code prompt

Important: Claude Code's terminal image-paste shortcut is Ctrl+V, not the normal macOS Cmd+V.

Capture the screen with Win+Shift+S
Press Alt+V in the Claude Code prompt

Copy a screenshot as image data
Press Ctrl+V in the Claude Code prompt

The current keybinding reference defines chat:imagePaste as Ctrl+V, with Alt+V as the Windows alternative.¹

Successful paste displays a chip such as [Image #1]. Wait for the chip before sending the prompt.

2. Drag and drop a file¶

Drag an image from Finder or Explorer into the terminal. This is convenient for Figma exports, saved screenshots, and design comparisons.

[Drag the image]
Recreate this screen in React and CSS. Explain the layout structure first.

Some terminals insert a file path instead of an image attachment. That path still works when Claude Code has permission to read the file.

3. Reference a file path¶

Paths make repository images and multi-image comparisons reproducible.

Compare ./screenshots/before.png with ./screenshots/after.png.
List UI regressions in severity order.

Absolute paths also work:

Read /tmp/repro/error.png and investigate the visible error
without changing code.

Quote paths containing spaces or use shell completion. Claude Code may request permission for files outside its current working scope.

Choose the method by source¶

Situation	Method	Why
Error currently on screen	Clipboard	Fastest path from capture to prompt
One exported design	Drag and drop	Direct selection from the file manager
Repository asset	File path	Easy to repeat the prompt
Before/after comparison	File paths	Makes the correspondence explicit
Only one region matters	Crop and paste	Reduces noise and payload size

Add a goal and constraints¶

An image alone does not say what should change or what must remain stable.

[Image #1]
Target viewport: 390px mobile width.
Match only the header and search-card spacing.
Do not change colors, fonts, or article-card DOM structure.
Before editing, explain no more than three likely differences.

For an error screen, add reproduction steps:

[Image #1]
1. Open Settings.
2. Press Save twice.
3. This error appears.
Read the logs and src/settings/, identify the cause, then propose a fix.

Anthropic's best-practices guide recommends rich context such as screenshots and mockups.³

Formats and current size limits¶

Common image formats are JPEG, PNG, GIF, and WebP. PNG works well for screenshots and text-heavy UI; JPEG or WebP usually keeps photos smaller.

The current error reference documents:²

An 8,000-pixel longest edge for a single image
A 2,000-pixel longest edge when several images are in context
A 30 MB limit for the overall API request

Claude Code may downscale an oversized pasted image, but a conversation can still fail when the combined images and context exceed the request limit.

When that happens:

Press Esc twice to return to the turn before the image
Crop to the relevant region
Resize the longest edge to 2,000 pixels or less
Remove images not needed for the current question
Split the images into a new conversation if necessary

With ImageMagick, write a new file rather than overwriting the original:

magick input.png -resize '2000x2000>' output.png

Open an attachment for verification¶

Image chips and links can be opened with Cmd+Click on macOS or Ctrl+Click on Windows/Linux. Exact behavior depends on the terminal or host application.¹

Before sending, confirm that [Image #N] appeared. After sending, ask Claude to identify a visible heading or region without making changes if you need to verify that the correct image is in context.

Troubleshooting¶

The paste shortcut does nothing¶

Use Ctrl+V, not Cmd+V, on macOS/Linux
Use Alt+V on Windows
Confirm the clipboard contains image data rather than a file-path string
Check for terminal-level keybinding conflicts
Save the image and reference its file path as a fallback

Text appears instead of an image¶

The source may not have put image data on the clipboard. Capture the screen again or save a PNG and provide its path.

Several images fail¶

Images can each be below 2,000 pixels and still exceed the combined 30 MB or context budget. Keep only the two images required for comparison and move the rest to another turn or conversation.

Summary¶

Use Ctrl+V, or Alt+V on Windows, for immediate screenshots
Use drag-and-drop or a path for saved files
State the goal, scope, and constraints along with the image
For errors, crop, resize to 2,000 pixels, and keep the request under 30 MB

The quality of the result depends more on identifying what to inspect and change than on the attachment method itself.