awfixers-stuff/ios-device-screenshot

iOS Device Screenshot

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

Installation

# 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:

# 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

pymobiledevice3 developer screenshot /path/to/screenshot.png

Quick Reference

# 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"

pymobiledevice3 mounter auto-mount --tunnel ""

Multiple devices connected

Specify the target device with --udid:

# 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:

# 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

#!/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