# IOS Device Screenshot

> Use when capturing screenshots from physical iOS devices connected via USB using pymobiledevice3.

- Skill: `tomevault-io/ios-device-screenshot` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/ios-device-screenshot`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/ios-device-screenshot/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/ios-device-screenshot

---


# iOS Device Screenshot

Take screenshots from physical iOS devices connected via USB using pymobiledevice3.

## Installation

```bash
# Install pymobiledevice3 using uv (recommended)
uv tool install pymobiledevice3

# Or with pipx
pipx install pymobiledevice3
```

## Prerequisites

1. **Physical iOS device** connected via USB
2. **Developer Mode enabled** on the device (Settings > Privacy & Security > Developer Mode)
3. **Device trusted** - approve "Trust This Computer" prompt on device

## Usage

### For iOS 17+ (including iOS 26+)

iOS 17+ requires a tunneld daemon running with root privileges:

```bash
# Terminal 1: Start tunneld (requires sudo, runs continuously)
sudo pymobiledevice3 remote tunneld

# Terminal 2: Take screenshot via DVT (Developer Tools)
pymobiledevice3 developer dvt screenshot --tunnel "" /path/to/screenshot.png
```

The `--tunnel ""` flag tells it to use the tunneld for device communication.

### For iOS 16 and earlier

```bash
pymobiledevice3 developer screenshot /path/to/screenshot.png
```

## Quick Reference

```bash
# List connected devices
xcrun devicectl list devices

# Check iOS version
ideviceinfo -k ProductVersion

# Check if developer image is mounted
ideviceimagemounter list

# Auto-mount developer image if needed
pymobiledevice3 mounter auto-mount --tunnel ""

# Take screenshot (iOS 17+) - single device
pymobiledevice3 developer dvt screenshot --tunnel "" ~/Desktop/screenshot.png

# Take screenshot with specific device UDID (required for multiple devices)
# First get UDIDs from: xcrun devicectl list devices
# Pass UDID directly to --tunnel (NOT --udid flag which doesn't work with tunneld)
pymobiledevice3 developer dvt screenshot --tunnel "00008101-001E05A41144001E" ~/Desktop/screenshot.png
```

**Important:** When multiple devices are connected, pass the UDID directly to `--tunnel` (not `--udid`). The `--tunnel ""` syntax prompts for interactive selection which fails in non-interactive shells.

## Troubleshooting

### "InvalidServiceError" or "Failed to start service"

1. Ensure tunneld is running: `ps aux | grep tunneld`
2. If not running: `sudo pymobiledevice3 remote tunneld`
3. Use the DVT command instead of regular screenshot: `developer dvt screenshot` instead of `developer screenshot`

### "DeveloperDiskImage not mounted"

```bash
pymobiledevice3 mounter auto-mount --tunnel ""
```

### Multiple devices connected

Specify the target device with `--udid`:

```bash
# List devices first
xcrun devicectl list devices

# Use specific UDID
pymobiledevice3 developer dvt screenshot --tunnel "" --udid "40182233-00C8-51ED-8C68-174E14E4B4C9" /tmp/screenshot.png
```

## Key Discovery

For iOS 17+, the regular `pymobiledevice3 developer screenshot` command often fails even with tunneld running. The solution is to use the DVT (Developer Tools) variant:

```bash
# This fails on iOS 17+:
pymobiledevice3 developer screenshot --tunnel "" /tmp/screenshot.png

# This works on iOS 17+:
pymobiledevice3 developer dvt screenshot --tunnel "" /tmp/screenshot.png
```

## Integration Example

```bash
#!/bin/bash
# Take iOS device screenshot and open it

OUTPUT="/tmp/ios-screenshot-$(date +%Y%m%d-%H%M%S).png"

# Check if tunneld is running, start if not
if ! pgrep -f "pymobiledevice3 remote tunneld" > /dev/null; then
    echo "Starting tunneld (requires sudo)..."
    sudo pymobiledevice3 remote tunneld &
    sleep 3
fi

# Take screenshot
pymobiledevice3 developer dvt screenshot --tunnel "" "$OUTPUT"

if [ -f "$OUTPUT" ]; then
    echo "Screenshot saved to: $OUTPUT"
    open "$OUTPUT"  # macOS: open in Preview
else
    echo "Failed to capture screenshot"
    exit 1
fi
```

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/0xbigboss) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->