iOS Device Toolkit
Drive a physical iOS device over USB with pymobiledevice3. This skill covers the high-value workflows; deep reference per area is in references/.
- Capture, logs, crashes →
references/capture.md
- Apps, app sandbox files, AFC media, debugserver →
references/apps-files.md
- Device info, perf, springboard, webinspector, tunneling →
references/diagnostics-perf.md
Install
# uv (preferred) or pipx
uv tool install pymobiledevice3
pipx install pymobiledevice3
pymobiledevice3 version # confirm; tested at 7.0.7
Prerequisites
- Physical iOS device attached via USB (or Wi-Fi-paired through usbmuxd).
- Developer Mode enabled on device (Settings → Privacy & Security → Developer Mode). Verify with
pymobiledevice3 mounter query-developer-mode-status.
- Trusted computer — accept "Trust This Computer" prompt on the device after first connect.
- iOS 17+ only: a long-running
tunneld daemon is required for any developer-mode service (screenshots, DVT instruments, debugserver, pcap-with-process, etc.). Start it once per boot:sudo pymobiledevice3 remote tunneld
The CLI auto-retries developer commands through tunneld; you no longer need --tunnel "" on every call in 7.x, though it still works.
Device selection
For a single attached device, no flag is needed. For multiple, scope every call with one of:
--udid <UDID> — usbmux-discovered device
--tunnel <UDID> — tunneld-discovered device (developer services on iOS 17+)
PYMOBILEDEVICE3_UDID=<UDID> / PYMOBILEDEVICE3_TUNNEL=<UDID> env vars — set once, all subsequent invocations inherit
Discover UDIDs:
pymobiledevice3 usbmux list # USB + Wi-Fi devices known to usbmuxd
xcrun devicectl list devices # Apple's own listing (macOS)
pymobiledevice3 lockdown info | head # full lockdown dump for the default device
Caveat: --tunnel "" (empty string) prompts interactively. In non-interactive shells, pass the UDID directly.
Quick reference
# --- Device info ---
pymobiledevice3 usbmux list
pymobiledevice3 lockdown info
pymobiledevice3 diagnostics battery
pymobiledevice3 mounter list
# --- Capture ---
# Screenshot (iOS 17+, DVT path — works where the deprecated developer screenshot fails)
pymobiledevice3 developer dvt screenshot ~/Desktop/shot.png
# Live syslog
pymobiledevice3 syslog live
# Crash reports
pymobiledevice3 crash ls
pymobiledevice3 crash pull ~/ios-crashes
# Packet capture (filter by process is optional)
pymobiledevice3 pcap --out trace.pcap --process Safari
# --- Apps ---
pymobiledevice3 apps list --user # only user-installed
pymobiledevice3 apps install ./MyApp.ipa
pymobiledevice3 apps uninstall com.example.MyApp
pymobiledevice3 developer dvt launch com.example.MyApp
pymobiledevice3 developer dvt process-id-for-bundle-id com.example.MyApp
pymobiledevice3 developer dvt kill <PID>
# --- Files (app sandbox + media) ---
pymobiledevice3 apps pull com.example.MyApp Documents/log.txt ./log.txt
pymobiledevice3 apps push com.example.MyApp ./seed.json Documents/seed.json
pymobiledevice3 afc pull DCIM/100APPLE/IMG_0001.HEIC ./
pymobiledevice3 afc ls -r DCIM
# --- Perf ---
pymobiledevice3 developer dvt sysmon system # one-shot system stats
pymobiledevice3 developer dvt sysmon process # per-process loop
pymobiledevice3 developer dvt proclist # PID + start times
pymobiledevice3 developer dvt energy <PID> [<PID>...]
# --- Networking / port forwarding ---
pymobiledevice3 usbmux forward 8080 8080 # local:8080 -> device:8080
pymobiledevice3 webinspector opened-tabs # requires Safari Web Inspector enabled on device
pymobiledevice3 webinspector cdp # CDP server for WebView debugging
Common gotchas
- "InvalidServiceError" / "Failed to start service" on iOS 17+ → tunneld is not running. Start
sudo pymobiledevice3 remote tunneld and retry. Confirm with ps aux | grep tunneld.
- "DeveloperDiskImage not mounted" →
pymobiledevice3 mounter auto-mount.
- Deprecated screenshot API hangs on iOS 17+ → use the DVT variant:
developer dvt screenshot (not developer screenshot).
--tunnel "" hangs in scripts → empty string means interactive picker; pass the UDID explicitly.
- Permissions on Linux → usbmuxd typically needs to be running; on macOS it's built in.
- Pairing lost after iOS update →
pymobiledevice3 lockdown unpair && pymobiledevice3 lockdown pair.
Scripting tips
- Set
PYMOBILEDEVICE3_UDID (and PYMOBILEDEVICE3_TUNNEL for developer services) once at the top of a script to avoid repeating flags.
- For capture-and-open recipes (screenshot +
open, syslog tail + grep, etc.), wrap in a shell function rather than re-typing the full path each time.
- Most subcommands accept
--rsd HOST PORT as an alternative to --tunnel, useful when you already have an RSD address from a manual pymobiledevice3 remote start-tunnel.
1---
2name: ios-device-toolkit
3description: Use when interacting with USB-attached iOS devices via pymobiledevice3 — screenshots, syslog, crash reports, app install/launch/pull, file transfer, sysmon perf, TCP port forwarding, WebInspector/CDP, and device diagnostics.
4metadata:
5 source: https://skillmd.com/skills/alleneubank/ios-device-toolkit
6---
7
8# iOS Device Toolkit
9
10Drive a physical iOS device over USB with `pymobiledevice3`. This skill covers the high-value workflows; deep reference per area is in `references/`.
11
12- Capture, logs, crashes → `references/capture.md`
13- Apps, app sandbox files, AFC media, debugserver → `references/apps-files.md`
14- Device info, perf, springboard, webinspector, tunneling → `references/diagnostics-perf.md`
15
16## Install
17
18```bash
19# uv (preferred) or pipx
20uv tool install pymobiledevice3
21pipx install pymobiledevice3
22
23pymobiledevice3 version # confirm; tested at 7.0.7
24```
25
26## Prerequisites
27
281. **Physical iOS device** attached via USB (or Wi-Fi-paired through usbmuxd).
292. **Developer Mode** enabled on device (Settings → Privacy & Security → Developer Mode). Verify with `pymobiledevice3 mounter query-developer-mode-status`.
303. **Trusted** computer — accept "Trust This Computer" prompt on the device after first connect.
314. **iOS 17+ only**: a long-running `tunneld` daemon is required for any developer-mode service (screenshots, DVT instruments, debugserver, pcap-with-process, etc.). Start it once per boot:
32 ```bash
33 sudo pymobiledevice3 remote tunneld
34 ```
35 The CLI auto-retries developer commands through tunneld; you no longer need `--tunnel ""` on every call in 7.x, though it still works.
36
37## Device selection
38
39For a single attached device, no flag is needed. For multiple, scope every call with one of:
40
41- `--udid <UDID>` — usbmux-discovered device
42- `--tunnel <UDID>` — tunneld-discovered device (developer services on iOS 17+)
43- `PYMOBILEDEVICE3_UDID=<UDID>` / `PYMOBILEDEVICE3_TUNNEL=<UDID>` env vars — set once, all subsequent invocations inherit
44
45Discover UDIDs:
46
47```bash
48pymobiledevice3 usbmux list # USB + Wi-Fi devices known to usbmuxd
49xcrun devicectl list devices # Apple's own listing (macOS)
50pymobiledevice3 lockdown info | head # full lockdown dump for the default device
51```
52
53Caveat: `--tunnel ""` (empty string) prompts interactively. In non-interactive shells, pass the UDID directly.
54
55## Quick reference
56
57```bash
58# --- Device info ---
59pymobiledevice3 usbmux list
60pymobiledevice3 lockdown info
61pymobiledevice3 diagnostics battery
62pymobiledevice3 mounter list
63
64# --- Capture ---
65# Screenshot (iOS 17+, DVT path — works where the deprecated developer screenshot fails)
66pymobiledevice3 developer dvt screenshot ~/Desktop/shot.png
67# Live syslog
68pymobiledevice3 syslog live
69# Crash reports
70pymobiledevice3 crash ls
71pymobiledevice3 crash pull ~/ios-crashes
72# Packet capture (filter by process is optional)
73pymobiledevice3 pcap --out trace.pcap --process Safari
74
75# --- Apps ---
76pymobiledevice3 apps list --user # only user-installed
77pymobiledevice3 apps install ./MyApp.ipa
78pymobiledevice3 apps uninstall com.example.MyApp
79pymobiledevice3 developer dvt launch com.example.MyApp
80pymobiledevice3 developer dvt process-id-for-bundle-id com.example.MyApp
81pymobiledevice3 developer dvt kill <PID>
82
83# --- Files (app sandbox + media) ---
84pymobiledevice3 apps pull com.example.MyApp Documents/log.txt ./log.txt
85pymobiledevice3 apps push com.example.MyApp ./seed.json Documents/seed.json
86pymobiledevice3 afc pull DCIM/100APPLE/IMG_0001.HEIC ./
87pymobiledevice3 afc ls -r DCIM
88
89# --- Perf ---
90pymobiledevice3 developer dvt sysmon system # one-shot system stats
91pymobiledevice3 developer dvt sysmon process # per-process loop
92pymobiledevice3 developer dvt proclist # PID + start times
93pymobiledevice3 developer dvt energy <PID> [<PID>...]
94
95# --- Networking / port forwarding ---
96pymobiledevice3 usbmux forward 8080 8080 # local:8080 -> device:8080
97pymobiledevice3 webinspector opened-tabs # requires Safari Web Inspector enabled on device
98pymobiledevice3 webinspector cdp # CDP server for WebView debugging
99```
100
101## Common gotchas
102
103- **"InvalidServiceError" / "Failed to start service" on iOS 17+** → tunneld is not running. Start `sudo pymobiledevice3 remote tunneld` and retry. Confirm with `ps aux | grep tunneld`.
104- **"DeveloperDiskImage not mounted"** → `pymobiledevice3 mounter auto-mount`.
105- **Deprecated screenshot API hangs on iOS 17+** → use the DVT variant: `developer dvt screenshot` (not `developer screenshot`).
106- **`--tunnel ""` hangs in scripts** → empty string means interactive picker; pass the UDID explicitly.
107- **Permissions on Linux** → usbmuxd typically needs to be running; on macOS it's built in.
108- **Pairing lost after iOS update** → `pymobiledevice3 lockdown unpair && pymobiledevice3 lockdown pair`.
109
110## Scripting tips
111
112- Set `PYMOBILEDEVICE3_UDID` (and `PYMOBILEDEVICE3_TUNNEL` for developer services) once at the top of a script to avoid repeating flags.
113- For capture-and-open recipes (screenshot + `open`, syslog tail + `grep`, etc.), wrap in a shell function rather than re-typing the full path each time.
114- Most subcommands accept `--rsd HOST PORT` as an alternative to `--tunnel`, useful when you already have an RSD address from a manual `pymobiledevice3 remote start-tunnel`.