# 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 | Primary Method | Alternative Method |
| --- | --- | --- |
| **Windows** | `Alt + V` | Drag & drop |
| **macOS** | `Ctrl + V` (not `Cmd + V`) | Drag & drop |
| **Linux** | `Ctrl + V` | Drag & drop or file path |
| **WSL (Windows)** | VS Code extension | File path 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)

```bash
# 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](https://marketplace.visualstudio.com/items?itemName=kkdev92.claude-imgpaste) 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:

```bash
"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:

```bash
"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](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code)
    
* [Claude Image Paste Extension (WSL)](https://marketplace.visualstudio.com/items?itemName=kkdev92.claude-imgpaste)
    
* [Claude Code GitHub Issues](https://github.com/anthropics/claude-code/issues)
    

---

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