Package: pymobiledevice3
NewsDescriptionInstallationOpenSSL librariesUsagePython APIWorking with developer tools (iOS >= 17.0)TunneldCommand UsageUsing TunneldExampleThe bits and bytesLockdown servicesImplemented servicesUn-implemented servicesSending your own messagesLockdown messagesInstruments messagesContributingUseful infoNewsSeeNEWS.Descriptionpymobiledevice3is a pure python3 implementation for working with iDevices (iPhone, etc...). This means this tool is
both architecture and platform generic and is supported and tested on:WindowsLinuxmacOSMain features include:Device discovery over bonjourTCP port forwardingViewing syslog lines (including debug)Profile managementApplication managementFile system management (AFC)Crash reports managementNetwork sniffing (PCAP)Firmware updateMounting imagesNotification listening and triggering (notify_post()api)Querying and setting SpringBoard optionsAutomating WebInspector featuresDeveloperDiskImage features:Taking screenshotsSimulate locationsProcess managementSniffing KDebug messages (stracecapabilities++)Process monitoring (toplike)Accessibility featuresSniffing oslog which includes both syslog and signpostsBackupInstallationYou can install from PyPi:python3-mpipinstall-Upymobiledevice3Or install the latest version directly from sources:gitclonegit@github.com:doronz88/pymobiledevice3.gitcdpymobiledevice3
python3-mpipinstall-U-e.You can also install auto-completion for all available sub-commands by adding the following into your~/.zshrc:# python-click<8.0eval"$(_PYMOBILEDEVICE3_COMPLETE=source_zshpymobiledevice3)"# python-click>=8.0eval"$(_PYMOBILEDEVICE3_COMPLETE=zsh_sourcepymobiledevice3)"OpenSSL librariesCurrently, openssl is explicitly required if using on older iOS version (<13).On macOS:brewinstallopensslOn Linux:sudoaptinstallopensslUsageThe CLI subcommands are divided roughly by the protocol layer used for interacting in the device. For example, all
features derived from the DeveloperDiskImage will be accessible from thedevelopersubcommand. This also means that every feature which isn't there won't require it.This is the main CLI usage:Usage: python -m pymobiledevice3 [OPTIONS] COMMAND [ARGS]...

Options:
  -h, --help  Show this message and exit.

Commands:
  activation       activation options
  afc              FileSystem utils
  amfi             amfi options
  apps             application options
  backup2          backup utils
  bonjour          bonjour options
  companion        companion options
  crash            crash report options
  developer        developer options.
  diagnostics      diagnostics options
  lockdown         lockdown options
  mounter          mounter options
  notification     notification options
  pcap             sniff device traffic
  power-assertion  Create a power assertion (wraps...
  processes        processes cli
  profile          profile options
  provision        privision options
  remote           remote options
  restore          restore options
  springboard      springboard options
  syslog           syslog options
  usbmux           usbmuxd options
  webinspector     webinspector options
  version          get installed package versionPython APIYou could also import the modules and use the API yourself:frompymobiledevice3.remote.remote_service_discoveryimportRemoteServiceDiscoveryServicefrompymobiledevice3.lockdownimportcreate_using_usbmuxfrompymobiledevice3.services.syslogimportSyslogService# Connecting via usbmuxdlockdown=create_using_usbmux()forlineinSyslogService(service_provider=lockdown).watch():# just print all syslog lines as isprint(line)# Or via remoted (iOS>=17)# First, create a tunnel using:#     $ sudo pymobiledevice3 remote start-tunnel# You can of course implement it yourself by copying the same pieces of code from:#     https://github.com/doronz88/pymobiledevice3/blob/master/pymobiledevice3/cli/remote.py#L68# Now you can simply connect to the created tunnel's host and porthost='fded:c26b:3d2f::1'# randomizedport=65177# randomizedwithRemoteServiceDiscoveryService((host,port))asrsd:forlineinSyslogService(service_provider=rsd).watch():# just print all syslog lines as isprint(line)Working with developer tools (iOS >= 17.0)NOTE:Currently, this is only supported on macOS & WindowsStarting at iOS 17.0, Apple introduced the new CoreDevice framework to work with iOS devices. This framework relies on
theRemoteXPCprotocol. In order to communicate with the developer services you'll be required to
first createtrusted tunnelas follows:# -- On macOSsudopython3-mpymobiledevice3remotestart-tunnel# -- On windows# Use a "run as administrator" shellpython3-mpymobiledevice3remotestart-tunnelThe root permissions are required since this will create a new TUN/TAP device which is a high privilege operation.
The output should be something similar to:Interface: utun6
RSD Address: fd7b:e5b:6f53::1
RSD Port: 64337
Use the follow connection option:
--rsd fd7b:e5b:6f53::1 64337Now, (almost) all of pymobiledevice3 accept an additional--rsdoption for connecting to the service over this new
tunnel. You can now try to execute any of them as follows:# Accessing the DVT servicespython3-mpymobiledevice3developerdvtls/--rsdfd7b:e5b:6f53::164337# Or any of the "normal" onespython3-mpymobiledevice3sysloglive--rsdfd7b:e5b:6f53::164337TunneldThe Tunneld Server is responsible for automatically creating a QUIC tunnel for Remote Service Discovery (RSD) when a
device is connected.Command UsageTo start the Tunneld Server, use the following command (with root privileges):# -- On macOSsudopython3-mpymobiledevice3remotetunneld# -- On windows# Use a "run as administrator" shellpython3-mpymobiledevice3remotetunneldUsing TunneldOnce the Tunneld Server is running, you can use it for RSD over the created QUIC tunnel.To specify a device by its UDID:python3-mpymobiledevice3remotersd-info--tunnelUDIDTo let Tunneld automatically select a device (if only one is connected):python3-mpymobiledevice3remotersd-info--tunnel''If no UDID is specified and multiple devices are connected, a prompt will appear for device selection.ExampleA recorded example for using a variety of features can be viewed at:https://terminalizer.com/view/18920b405193There is A LOT you may do on the device usingpymobiledevice3. This is just a TL;DR of some common operations:Listing connected devices:pymobiledevice3 usbmux listDiscover network devices using bonjour:pymobiledevice3 bonjour browseView all syslog lines (including debug messages):pymobiledevice3 syslog liveFilter out only messages containing the word "SpringBoard":pymobiledevice3 syslog live -m SpringBoardRestart device:pymobiledevice3 diagnostics restartPull all crash reports from device:pymobiledevice3 crash pull /path/to/crashesManage the media directory:pymobiledevice3 afc shellList all installed applications and their details:pymobiledevice3 apps listList query only a specific set os apps:pymobiledevice3 apps query BUNDLE_ID1 BUNDLE_ID2Create a TCP tunnel from your HOST to the device:pymobiledevice3 usbmux forward HOST_PORT DEVICE_PORTCreate a full backup of the device:pymobiledevice3 backup2 backup --full DIRECTORYRestore a given backup:pymobiledevice3 backup2 restore DIRECTORYThe following will require Web Inspector feature to be turned on:Get interactive JavaScript shell on any open tab:pymobiledevice3 webinspector js_shellList currently opened tabs is device's browser:pymobiledevice3 webinspector opened-tabsThe following will require also the Remote Automation feature to be turned on:Get interactive JavaScript shell on new remote automation tab:pymobiledevice3 webinspector js_shell --automationLaunch an automation session to view a given URL:pymobiledevice3 webinspector launch URLGet a a selenium-like shell:pymobiledevice3 webinspector shellMount DeveloperDiskImage (On iOS>=17.0, each command will require an additional--rsdoption):pymobiledevice3 mounter auto-mountThe following will assume the DeveloperDiskImage is already mounted:Simulate anx ylocation:pymobiledevice3 developer simulate-location set x yOr the following for iOS>=17.0:pymobiledevice3 developer dvt simulate-location set --rsd HOST PORT -- x yTaking a screenshot from the device:pymobiledevice3 developer dvt screenshot /path/to/screen.pngView detailed process list (including ppid, uid, guid, sandboxed, etc...):pymobiledevice3 developer dvt sysmon process singleSniffing oslog:pymobiledevice3 developer dvt oslogKill a process:pymobiledevice3 developer dvt kill PIDList files in a given directory (un-chrooted):pymobiledevice3 developer dvt ls PATHLaunch an app by its bundle name:pymobiledevice3 developer dvt launch com.apple.mobilesafariSniff all KDebug events to get anstrace-like output:pymobiledevice3 developer dvt core-profile-session parse-liveSniff all KDebug events into a file for parsing later with tools such
aspykdebugparser,fs_usageand so on...pymobiledevice3 developer dvt core-profile-session save FILENAMEGet device extended information (kernel name, chipset, etc...):pymobiledevice3 developer dvt device-informationMonitor energy-consumption for a specific PID:pymobiledevice3 developer dvt energy PID1 PID2 ...The bits and bytesTo understand the bits and bytes of the communication with lockdownd you are advised to take a look at this article:https://jon-gabilondo-angulo-7635.medium.com/understanding-usbmux-and-the-ios-lockdown-service-7f2a1dfd07aeLockdown servicesImplemented servicesThis is the list of all the services fromlockdowndwhich we reversed and implemented API wrappers for. A click on
each will lead to each one's implementation, where you can learn more about.com.apple.mobile.heartbeatJust a ping tolockdowndservice.Used to keep an active connection withlockdowndcom.apple.mobileactivationdActivation servicescom.apple.afcFile access for/var/mobile/MediaBased on afcd's protocolcom.apple.crashreportcopymobileFile access for/var/mobile/Library/Logs/CrashReportsBased on afcd's protocolcom.apple.pcapdSniff device's network trafficcom.apple.syslog_relayJust streams syslog lines as raw stringsFor a more robust structural parsing, it's better to access thecom.apple.os_trace_relayrelay.com.apple.os_trace_relayMore extensive syslog monitoringcom.apple.mobile.diagnostics_relayGeneral diagnostic toolscom.apple.mobile.notification_proxy&com.apple.mobile.insecure_notification_proxyAPI wrapper fornotify_post()&notify_register_dispatch()com.apple.crashreportmoverJust triggercrash_moverto move all crash reports into crash directorycom.apple.mobile.MCInstallProfile management (MDM)com.apple.misagentProvisioning Profiles managementcom.apple.companion_proxyCompanion features (watches and etc.)com.apple.mobilebackup2Local backup managementcom.apple.mobile.assertion_agentCreate power assertion to prevent different kinds of sleepcom.apple.springboardservicesPlay with device's button layoutcom.apple.mobile.mobile_image_mounterImage mounter service (used for DeveloperDiskImage mounting)com.apple.mobile.house_arrestGet AFC utils (file management per application bundle)com.apple.mobile.installation_proxyApplication managementcom.apple.instruments.remoteserverDeveloper instrumentation service, iOS<14  (DeveloperDiskImage)com.apple.instruments.remoteserver.DVTSecureSocketProxyDeveloper instrumentation service, iOS>=14  (DeveloperDiskImage)com.apple.mobile.screenshotrTake screenshot into a PNG format (DeveloperDiskImage)com.apple.accessibility.axAuditDaemon.remoteserverAccessibility features (DeveloperDiskImage)com.apple.dt.simulatelocationAllows to simulate locations (DeveloperDiskImage)com.apple.dt.fetchsymbolsAllows fetching ofdyldand dyld shared cache files (DeveloperDiskImage)com.apple.webinspectorUsed to debug WebViewscom.apple.amfi.lockdownUsed to enable developer-modeUn-implemented servicesThis is the list of services we haven't dedicated time in implementing. If you feel the need to use one of them or any
other that is not listed in here, feel free
tocreate us an issue request.com.apple.idamdAllows settings the IDAM configuration (something to do with loading of AppleUSBDeviceAudioDevice)com.apple.atcAirTraffic relatedcom.apple.atc2com.apple.ait.aitdAirTraffic relatedcom.apple.mobile.file_relay(Deprecated)On older iOS versions (iOS <= 8), this was the main relay used for file operations, which was later replaced with
AFC.com.apple.mobilesynccom.apple.purpletestr(Deprecated)com.apple.PurpleReverseProxy.ConnSomething to do with tethering internet connection to restored devicescom.apple.PurpleReverseProxy.CtrlSomething to do with tethering internet connection to restored devicescom.apple.dt.remotepairingdeviced.lockdowncom.apple.commcenter.mobile-helper-cbupdateservicecom.apple.carkit.serviceUsed to transfer data to accessories. Data is transferred using iAP2 packets.com.apple.bluetooth.BTPacketLoggercom.apple.streaming_zip_conduitAnother relay used to install IPAsSending your own messagesLockdown messagesEvery such subcommand may wrap several relay requests underneath. If you wish to try and play with some the relays
yourself, you can run:pymobiledevice3lockdownservice<service-name>This will start an IPython shell where you already have the connection established using theclientvariable and you
can send & receive messages.# This shell allows you to communicate directly with every service layer behind the lockdownd daemon.# For example, you can do the following:client.send_plist({"Command":"DoSomething"})# and view the replyprint(client.recv_plist())# or just send raw messageclient.sendall(b"hello")# and view the resultprint(client.recvall(20))Instruments messagesIf you want to play withDTServiceHubwhich lies behind thedeveloperoptions, you can also use:pymobiledevice3developershellTo also get an IPython shell, which lets you call ObjC methods from the exported objects in the instruments' namespace
like so:# This shell allows you to send messages to the DVTSecureSocketProxy and receive answers easily.# Generally speaking, each channel represents a group of actions.# Calling actions is done using a selector and auxiliary (parameters).# Receiving answers is done by getting a return value and seldom auxiliary (private / extra parameters).# To see the available channels, type the following:developer.supported_identifiers# In order to send messages, you need to create a channel:channel=developer.make_channel('com.apple.instruments.server.services.deviceinfo')# After creating the channel you can call allowed selectors:channel.runningProcesses()# If an answer is expected, you can receive it using the receive method:processes=channel.receive_plist()# Sometimes the selector requires parameters, You can add them using MessageAux. For example lets kill a process:channel=developer.make_channel('com.apple.instruments.server.services.processcontrol')args=MessageAux().append_obj(80)# This will kill pid 80channel.killPid_(args,expects_reply=False)# Killing a process doesn't require an answer.# In some rare cases, you might want to receive the auxiliary and the selector return value.# For that cases you can use the recv_plist method.return_value,auxiliary=developer.recv_plist()ContributingSeeCONTRIBUTING.Useful infoPlease seemisc