ios-device-screenshot

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

iOS Device Screenshot

iOS设备截图

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

使用pymobiledevice3对通过USB连接的物理iOS设备进行截图。

Installation

安装

bash

undefined

bash

undefined

Install pymobiledevice3 using uv (recommended)

使用uv安装pymobiledevice3（推荐）

uv tool install pymobiledevice3

Or with pipx

或使用pipx

pipx install pymobiledevice3

undefined

pipx install pymobiledevice3

undefined

Prerequisites

前置条件

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

物理iOS设备通过USB连接
设备上已启用开发者模式（设置 > 隐私与安全性 > 开发者模式）
设备已信任 - 在设备上确认“信任此电脑”提示

Usage

使用方法

For iOS 17+ (including iOS 26+)

适用于iOS 17+（包括iOS 26+）

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

bash

undefined

iOS 17+要求以root权限运行tunneld守护进程：

bash

undefined

Terminal 1: Start tunneld (requires sudo, runs continuously)

终端1：启动tunneld（需要sudo，持续运行）

sudo pymobiledevice3 remote tunneld

Terminal 2: Take screenshot via DVT (Developer Tools)

终端2：通过DVT（开发者工具）截图

pymobiledevice3 developer dvt screenshot --tunnel "" /path/to/screenshot.png


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

pymobiledevice3 developer dvt screenshot --tunnel "" /path/to/screenshot.png


`--tunnel ""`参数表示使用tunneld进行设备通信。

For iOS 16 and earlier

适用于iOS 16及更早版本

bash

pymobiledevice3 developer screenshot /path/to/screenshot.png

bash

pymobiledevice3 developer screenshot /path/to/screenshot.png

Quick Reference

快速参考

bash

undefined

bash

undefined

List connected devices

列出已连接设备

xcrun devicectl list devices

Check iOS version

查看iOS版本

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

截图（iOS 17+）- 单设备

pymobiledevice3 developer dvt screenshot --tunnel "" ~/Desktop/screenshot.png

Take screenshot with specific device UDID (required for multiple devices)

针对特定设备UDID截图（多设备连接时需指定）

First get UDIDs from: xcrun devicectl list devices

首先从以下命令获取UDID：xcrun devicectl list devices

Pass UDID directly to --tunnel (NOT --udid flag which doesn't work with tunneld)

直接将UDID传递给--tunnel（不能使用--udid参数，该参数与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.

pymobiledevice3 developer dvt screenshot --tunnel "00008101-001E05A41144001E" ~/Desktop/screenshot.png


**重要提示：** 当连接多个设备时，直接将UDID传递给`--tunnel`（而非`--udid`）。`--tunnel ""`语法会触发交互式选择，在非交互式shell中会执行失败。

Troubleshooting

故障排除

"InvalidServiceError" or "Failed to start service"

"InvalidServiceError"或"Failed to start service"

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

确认tunneld正在运行：
```
ps aux | grep tunneld
```
若未运行：
```
sudo pymobiledevice3 remote tunneld
```
使用DVT命令而非常规截图命令：使用
```
developer dvt screenshot
```
替代
```
developer screenshot
```

"DeveloperDiskImage not mounted"

bash

pymobiledevice3 mounter auto-mount --tunnel ""

bash

pymobiledevice3 mounter auto-mount --tunnel ""

Multiple devices connected

多设备连接

Specify the target device with

--udid

bash

undefined

使用

--udid

指定目标设备：

bash

undefined

List devices first

先列出设备

xcrun devicectl list devices

Use specific UDID

使用特定UDID

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

undefined

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

undefined

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

undefined

对于iOS 17+，即使tunneld正在运行，常规的

pymobiledevice3 developer screenshot

命令通常也会执行失败。解决方案是使用DVT（开发者工具）变体命令：

bash

undefined

This fails on iOS 17+:

该命令在iOS 17+上会失败：

pymobiledevice3 developer screenshot --tunnel "" /tmp/screenshot.png

This works on iOS 17+:

该命令在iOS 17+上可正常工作：

pymobiledevice3 developer dvt screenshot --tunnel "" /tmp/screenshot.png

undefined

pymobiledevice3 developer dvt screenshot --tunnel "" /tmp/screenshot.png

undefined

Integration Example

集成示例

bash

#!/bin/bash

bash

#!/bin/bash

Take iOS device screenshot and open it

捕获iOS设备截图并打开

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

Check if tunneld is running, start if not

检查tunneld是否运行，若未运行则启动

if ! pgrep -f "pymobiledevice3 remote tunneld" > /dev/null; then echo "Starting tunneld (requires sudo)..." sudo pymobiledevice3 remote tunneld & sleep 3 fi

if ! pgrep -f "pymobiledevice3 remote tunneld" > /dev/null; then echo "正在启动tunneld（需要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

undefined

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

if [ -f "$OUTPUT" ]; then echo "截图已保存至: $OUTPUT" open "$OUTPUT" # macOS：在预览中打开 else echo "截图捕获失败" exit 1 fi

undefined