Claude Code Image Attachment Guide — 3 Methods and When to Use Each¶
For / Key Points
For: Engineers who want to use images in Claude Code conversations but are unsure about attachment methods or limitations
Key Points:
- Three methods — drag-and-drop, clipboard, and file path — each suited to different workflows
- Supports JPEG/PNG/GIF/WebP with a 5MB per image limit and 8000×8000px max resolution
- Image preview feature (v2.0.73+) lets you verify attachments directly in the terminal
Three Attachment Methods¶
Drag and Drop¶
The most intuitive method.
# Start Claude Code in terminal
claude
# Drag and drop an image file onto the terminal window
# → Image is automatically attached, waiting for prompt input
Best Use Cases
Perfect for sharing UI mockups, error screenshots, and design files.
Clipboard Paste¶
Paste screen captures directly.
1. Take a screenshot with Cmd + Shift + 4
2. While typing a prompt in Claude Code, press Ctrl + V to paste
Important
On macOS, use Ctrl + V, not Cmd + V.
1. Take a screenshot using your preferred method (Win + Shift + S, etc.)
2. While typing a prompt in Claude Code, press Ctrl + V to paste
File Path Reference¶
Reference images in your working directory by path.
claude
> Analyze /path/to/screenshot.png and identify UI issues
Relative paths also work:
> Implement ./images/mockup.png as a React component
When to Use Each Method¶
Choose based on where the image comes from.
| Situation | Recommended Method | Why |
|---|---|---|
| Sharing a browser or app error screen quickly | Clipboard | Screenshot → paste instantly for fastest workflow |
| Have an exported file from Figma, etc. | Drag and Drop | Locate the file and drop it directly |
| Referencing CI log images or repo assets | File Path | Just copy the path to attach |
| Analyzing multiple images at once | File Path | List multiple paths in one prompt |
Practical Examples¶
Drag and Drop: Implementing from Design Mockups¶
claude
> [Drag and drop Figma export image]
> Implement this design using React + Tailwind CSS
Clipboard: Instant Error Screen Sharing¶
# 1. Capture the error screen with Cmd+Shift+4 (macOS)
# 2. Switch to Claude Code and press Ctrl+V to paste
claude
> Identify the root cause of this error. Please also fix the relevant code
File Path: Batch Analysis of Multiple Images¶
claude
> Compare ./screenshots/before.png and ./screenshots/after.png
> and check for any UI regressions
Supported Formats and Limitations¶
Supported Formats¶
| Format | Characteristics | Recommended Use |
|---|---|---|
| JPEG | High compression, photo-friendly | UI photos, device captures |
| PNG | Transparency support, lossless | Screenshots, images with text |
| GIF | Animation support | Sharing procedures (first frame only analyzed) |
| WebP | High efficiency, small files | Optimized images |
Size and Resolution Limits¶
| Item | Limit |
|---|---|
| Max size per image | 5MB |
| Max resolution | 8000 × 8000 px |
| Recommended resolution | 1000 × 1000 px or higher |
| Max images per request | 100 |
| Total size for multiple images | 32MB |
When Exceeding 20 Images
Attaching more than 20 images limits max resolution to 2000 × 2000 px.
Image Preview Feature¶
Verify attached images directly in the terminal (added in v2.0.73).
Clickable Image Links¶
Attached images now display a clickable [Image #N] link.
[Image #1] screenshot.png (1.2MB)
Click the link to open in your default image viewer.
Terminal Compatibility¶
| Terminal | Click Support |
|---|---|
| iTerm2 | |
| ghostty | |
| WezTerm | |
| VS Code integrated terminal | |
| macOS Terminal.app |
Troubleshooting¶
Clipboard Paste Not Working¶
| Symptom | Cause | Solution |
|---|---|---|
| Nothing pastes | Wrong shortcut key | Use Ctrl+V on macOS |
| Garbled output | Terminal compatibility | Switch to iTerm2 or WezTerm |
| Large images fail | Size limit exceeded | Resize to under 5MB |
Image Not Recognized¶
# Check image format
file /path/to/image.png
# Check file size
ls -lh /path/to/image.png
# Resize if needed (using ImageMagick)
convert input.png -resize 2000x2000\> output.png
Image Resize One-liner
# Auto-compress images over 5MB
find . -name "*.png" -size +5M -exec convert {} -resize 2000x2000\> {} \;
Related Articles¶
- Claude Code Image Integration Guide - Visual-driven development with images
- Claude Code Complete Guide - Comprehensive feature overview
- Claude Code Best Practices - Effective usage tips