Pasting Images in Claude Code: Complete Cross-Platform Guide

Working with Claude Code and need to share screenshots, mockups, or design references? Here's the definitive guide for pasting images across all platforms.

Quick Reference

Platform-Specific Instructions

Windows (Native)

Method 1: Keyboard Shortcut (Recommended)

1. Take a screenshot or copy an image to clipboard

2. Switch to Claude Code

3. Press Alt + V to paste

Note: This shortcut was added in Claude Code version 1.0.93. Make sure you're running the latest version.

Method 2: Drag & Drop

• Simply drag an image file from Windows Explorer directly into the Claude Code terminal

---

macOS

Method 1: Keyboard Shortcut (Recommended)

1. Take a screenshot (Cmd + Shift + 4 for selection, Cmd + Shift + 3 for full screen)

2. Switch to Claude Code

3. Press Ctrl + V (not Cmd + V)

Important: Unlike most Mac apps, Claude Code uses Ctrl + V instead of Cmd + V for pasting images.

Method 2: Drag & Drop

• Drag an image file from Finder directly into the Claude Code terminal

---

Linux (Ubuntu, Debian, etc.)

Method 1: Keyboard Shortcut

1. Take a screenshot (varies by desktop environment)

   • GNOME: PrtScn or Shift + PrtScn

   • KDE: Spectacle or PrtScn

2. Switch to Claude Code terminal

3. Press Ctrl + V

Known Issue: Image pasting from clipboard may not work reliably in some terminal emulators (gnome-terminal, xterm). See workarounds below.

Method 2: File Path Reference (Most Reliable)

# Save your screenshot first, then reference it
"Here's the design mockup: /home/username/screenshots/mockup.png"

Method 3: Drag & Drop

• If using VS Code with Claude Code extension, drag the image file into the terminal

---

Windows Subsystem for Linux (WSL)

WSL presents unique challenges because clipboard and file system access differs from native Windows.

Recommended Solution: VS Code Extension

Install the Claude Image Paste extension or similar:

1. Open VS Code Extensions (Ctrl + Shift + X)

2. Search for "Claude Image Paste"

3. Install the extension

4. Take a screenshot in Windows

5. In VS Code terminal with Claude Code, press Ctrl + V

The extension automatically:

• Saves clipboard images to your WSL file system

• Converts Windows paths to WSL paths

• Sends the correct file path to Claude Code

Alternative: Manual File Path

1. Save screenshot to a location accessible from WSL

2. Convert Windows path to WSL path:

   • Windows: C:\Users\YourName\Pictures\mockup.png

   • WSL: /mnt/c/Users/YourName/Pictures/mockup.png

3. Reference in Claude Code: "Check out /mnt/c/Users/YourName/Pictures/mockup.png"

---

Universal Methods (All Platforms)

Drag & Drop

Works on Windows, macOS, and Linux (with GUI):

1. Open your file manager

2. Drag the image file directly into the Claude Code terminal window

3. Drop to upload

File Path Reference

If you already have images in your project:

"Analyze the design in ./assets/mockup.png"
"Look at the screenshot I saved: ~/Documents/bug-screenshot.png"
"Compare these two: /path/to/design-v1.png and /path/to/design-v2.png"

Claude Code can access any file path you reference directly.

---

Troubleshooting

"Nothing happens when I paste"

On macOS: Make sure you're using Ctrl + V, not Cmd + V

On Windows:

• Update to Claude Code version 1.0.93 or later

• Try Alt + V instead of Ctrl + V

On Linux:

• Terminal emulator limitations may prevent clipboard image pasting

• Use file path method or drag & drop instead

• Consider using VS Code with Claude Code extension

"Image quality is poor"

Claude Code supports these formats with good quality retention:

• PNG (best for screenshots and UI)

• JPG/JPEG (good for photos)

• WebP, GIF, BMP, SVG, TIFF

For best results with UI mockups, use PNG format.

"WSL path conversion errors"

Common path translation issues:

• Windows C:\ becomes /mnt/c/ in WSL

• Use forward slashes / not backslashes \

• Ensure file has read permissions in WSL: chmod +r filename.png

---

Pro Tips

1. Screenshot + Instant Paste Workflow

• Windows: Win + Shift + S → select area → Alt + V in Claude Code

• macOS: Cmd + Shift + 4 → select area → Ctrl + V in Claude Code

• Linux: PrtScn → Ctrl + V in Claude Code (if supported)

2. Batch Image Processing

You can reference multiple images in one prompt:

"Compare these designs and build the best version:
- Design A: ./mockups/version-a.png
- Design B: ./mockups/version-b.png
- Design C: ./mockups/version-c.png"

3. Iterative Design Workflow

1. Paste mockup → Claude generates code

2. Screenshot the result → Paste again

3. Ask Claude to compare and refine

4. Repeat until perfect

4. VS Code Integration

For the smoothest experience, especially on WSL:

• Use VS Code with Claude Code extension

• Install clipboard helper extensions

• Configure custom save directories for pasted images

• Enable auto-naming with timestamps

---

Why Pasting Images Matters

Claude Code's vision capabilities unlock powerful workflows:

• UI Development: Show a mockup, get production code

• Bug Reports: Screenshot the issue, Claude debugs it

• Design Iteration: Visual feedback loop between design and code

• Documentation: Reference diagrams and architecture drawings

• Code Review: Highlight problematic UI elements

Visual context transforms Claude Code from a text-based assistant into a true collaborative development partner.

---

Additional Resources

• Official Claude Code Documentation

• Claude Image Paste Extension (WSL)

• Claude Code GitHub Issues

---

Last Updated: December 2025
Tested On: Claude Code v1.0.93+, Windows 11, macOS Sonoma, Ubuntu 22.04