Install & Compatibility
Where this runs
tested against v9.18.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.13
✕ build_error
✕ build_error
186MB installed
● package 186MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
create_using_usbmux
✓ from pymobiledevice3.lockdown import create_using_usbmux
SyslogService
✓ from pymobiledevice3.services.syslog import SyslogService
LockdownClient
✓ from pymobiledevice3.lockdown import LockdownClient
✗ from pymobiledevice3.lockdown import LockdownService
LockdownClient is the primary entry point for managing lockdown services, not LockdownService.
This quickstart demonstrates how to connect to a USB-attached iOS device and stream its syslog using the PyMobileDevice3 Python API. It includes necessary imports and basic error handling for common setup issues. Ensure your device is connected and trusted before running.
import asyncio
import os
from pymobiledevice3.lockdown import create_using_usbmux
from pymobiledevice3.services.syslog import SyslogService
async def main():
# This example connects to a USB-connected and trusted iOS device
# and streams its syslog output.
try:
lockdown = await create_using_usbmux()
device_name = lockdown.get_device_name()
device_udid = lockdown.udid
print(f"Connected to device: {device_name} (UDID: {device_udid})")
syslog_service = SyslogService(service_provider=lockdown)
print("\nStreaming syslog (press Ctrl+C to stop)...\n")
async for line in syslog_service.watch():
print(line)
except Exception as e:
print(f"\nError: {e}")
print("Please ensure:")
print("1. An iOS device is connected via USB and is trusted by your computer.")
print("2. On Linux, 'usbmuxd' is installed and running. On Windows, iTunes is installed.")
print("3. For older iOS versions (<13), OpenSSL is installed.")
print("4. If accessing developer services on iOS 17+, a tunnel is established (e.g., 'sudo python3 -m pymobiledevice3 remote start-tunnel').")
if __name__ == '__main__':
asyncio.run(main())
pymobiledevice3 --version
Debug
Known issues
breakingFor iOS 17.0 and later, developer services require tunnel-based transport (e.g., `tunneld` or `start-tunnel`) due to Apple's new CoreDevice framework. Direct connections to developer services will fail without a tunnel.fixBefore using developer services, establish a tunnel. You can use `sudo python3 -m pymobiledevice3 remote tunneld` to automatically detect devices and establish connections, or manually create one with `sudo python3 -m pymobiledevice3 remote start-tunnel`.
affects: >=17.0 (iOS)
breakingThe CLI command `start-quic-tunnel` was renamed to `start-tunnel` (e.g. for creating developer tunnels). Scripts using the old command will break.fixUpdate scripts to use `pymobiledevice3 remote start-tunnel` instead of `pymobiledevice3 remote start-quic-tunnel`.
affects: >=2.31.0 (pymobiledevice3)
gotchaPlatform-specific external dependencies are required for PyMobileDevice3 to function. Windows users need iTunes, Linux users need `usbmuxd`, and for Recovery/DFU mode or older iOS versions, `libusb` and `OpenSSL` might be necessary.fixInstall the appropriate system-level dependencies for your operating system as specified in the documentation (e.g., `usbmuxd` on Linux, iTunes on Windows).
affects: All versions
gotchaWhen bundling PyMobileDevice3 into an executable (e.g., using PyInstaller), there can be a significant performance overhead and startup delay (up to 10 seconds or more) compared to running directly from an installed Python environment.fixBe aware of this performance characteristic when designing deployments. Consider alternative deployment strategies or accept the startup overhead. This is generally due to the 'bundled python' overhead.
affects: All versions when bundled
Upgrade
Version history
9.18.0latest on PyPI · released Jun 11, 2026
Audit
Dependencies
usbmuxdrequiredRequired on Linux for device communication. Typically installed via `sudo apt install usbmuxd` on Debian/Ubuntu.
iTunesrequiredRequired on Windows for device communication.
OpenSSLoptionalExplicitly required for interacting with iOS versions older than 13. Install via `brew install openssl` (macOS) or `sudo apt install openssl` (Linux).
libusboptionalRequired for Recovery/DFU mode interactions (e.g., restore subcommands). Installation varies by OS.