CLI tool
doronz88/pymobiledevice3 avatar
doronz88/pymobiledevice3

pymobiledevice3: a pure Python 3 toolkit for talking to iPhones over usbmux

Pure python3 implementation for working with iDevices (iPhone, etc...).

3,078 stars439 forksPythonGPL-3.0

At a glance

What is it?
pymobiledevice3 gives Python developers a CLI and an importable API for lockdown services, AFC, syslog, backups and iOS 17+ tunnels. It is GPL-3.0, requires Python 3.9 or newer, and assumes you are comfortable with a terminal.
Who is it for?
Adopt pymobiledevice3 if you already write Python and need scripted access to a connected iPhone or iPad: device discovery, AFC file access, syslog streaming, backups, and the DDI/DVT developer tooling that iOS 17 and later require over a tunnel. Do not adopt it if you need a supported, vendor-blessed path, if you cannot accept GPL-3.0 terms in your distribution, or if you are unwilling to manage tunnel and pairing state yourself.
Can I use it commercially?
Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
Is it still maintained?
Yes. The repository last received commits 2 days ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • doronz88/pymobiledevice33,078 ★ · +240
Star history
Repository2026-10-042026-11-21
doronz88/pymobiledevice32.8k3.1k

240 Stars in the last 48 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What pymobiledevice3 replaces, and who ends up using it

The project describes itself as a pure Python 3 implementation for interacting with iOS devices. That word, pure, is the whole pitch. There is no C library to compile, no libimobiledevice shared object to find on your system, no ctypes shim. You install a Python package and you get both a command-line tool and an importable API, on Windows, Linux, and macOS.

The practical audience is narrow but deep. Test engineers who need to pull crash reports or push a build to a device from a CI runner. Security researchers reading syslog or sniffing traffic with the PCAP support. Developers who want Chrome DevTools, VS Code or Playwright attached to a WebView running on a physical iPhone, which the README calls a CDP bridge. Nobody reaches for this to ship an App Store app. It is a host-side control plane, and the device is the thing being controlled.

If you have used libimobiledevice's ideviceinfo or ideviceinstaller, the mental model transfers directly. The difference is that the protocol layers are Python objects you can subclass and inspect, and the CLI is one entry point rather than a scattered set of binaries.

How the lockdown, AFC and tunnel layers fit together

Everything starts at usbmux, the multiplexer that lets a host reach services on a device plugged in over USB. The README lists usbmux as a topic alongside lockdownd, and the CLI exposes it directly: usbmux list enumerates attached devices.

Above that sits lockdownd, the daemon that hands out access to individual services. Once a session is established, pymobiledevice3 can request a service by name and speak its protocol. AFC is the file-access service, which is what makes file transfer and app container browsing possible. Syslog and oslog are streaming services, so the CLI surfaces them as live tails rather than one-shot queries. Crash reports, profiles, and backups each ride their own service.

The layer that has changed most is the developer tooling. The README states that DDI and DVT developer tooling on iOS 17 and later runs over a tunnel, and it links a dedicated support matrix for iOS 17+ tunnels. That is a real architectural shift: the older direct-service model does not cover everything on modern firmware. The repository also documents protocol internals under RemoteXPC, DTX, and iDevice protocol layers, which tells you the maintainers expect users to need that depth when something breaks.

One design consequence worth naming: because this is a reimplementation rather than a binding, protocol coverage is whatever the project has implemented so far. The docs point at a support matrix precisely because coverage is version-dependent.

Installing pymobiledevice3 on macOS, Windows and Ubuntu with pip

The README gives one install command, and it is the same on every platform: a pip install of the package. Python 3.9 is the floor according to pyproject.toml, and classifiers list 3.9 through 3.15.

bash
python3 -m pip install -U pymobiledevice3

On macOS and Linux the system Python may be externally managed, so a virtual environment is the safer route. On Windows, use the py launcher if python3 is not on PATH. The README does not document a per-platform install path beyond this command, and the installation page in the docs is where platform notes live.

After installing, verify that the host can see a device at all. This is the first real use, and it is deliberately cheap:

bash
pymobiledevice3 usbmux list

The README shows this as the connectivity check. You should see your attached device enumerated. If the list is empty, the problem is usually the cable, the trust prompt on the device, or a missing USB driver on Windows, not the package.

Two more commands from the README confirm that the higher layers work. The first streams device logs; the second lists installed applications.

bash
pymobiledevice3 syslog live
pymobiledevice3 apps list

syslog live is a tail, so it will keep printing until you interrupt it. If you get device output there, your lockdown session and service requests are working, and you can move on to the CLI recipes in the docs.

The GPL-3.0 boundary and what it means for your build

The licence is GPL-3.0-or-later according to pyproject.toml, and the README states the work is licensed under GPL 3.0. This is not a permissive licence with a notice requirement. If you import pymobiledevice3 into a tool you distribute, the copyleft terms are the ones you have to reason about, and the project does not offer a dual-licence escape hatch in the repository files.

That matters more than usual here, because the natural use is internal tooling. An in-house test harness that never leaves the company is a very different question from a commercial desktop app that bundles the package. I am not giving legal advice, and the repository does not discuss linking exceptions or commercial licensing. If your distribution model depends on keeping source closed, that is the thing to resolve before you build on this, not after.

There is a second, quieter cost: the dependency list in pyproject.toml is long. construct, construct-typing, asn1, cryptography, pyusb, xonsh, IPython, and more. Note the conditional pin on construct-typing: 0.8.0 or newer on Python 3.10 and up, but held below 0.8.0 on 3.9 because the newer release requires 3.10. That is a maintainer keeping a 3.9 floor alive at the cost of a split dependency spec. It also means your 3.9 environment is on a different code path than a 3.12 one, which is worth knowing when you file a bug.

Where pymobiledevice3 is the wrong tool

The clearest limitation is the one the project itself flags: iOS 17 and later move developer tooling onto a tunnel, and the README points to a support matrix rather than claiming universal coverage. If your fleet spans several iOS versions, you are managing two access models, and the older one does not do everything.

The second is operational. This is a host-side tool that assumes a physically attached or network-reachable device with a trusted pairing. There is no device farm here, no queue, no retry semantics for a device that unplugged mid-backup. You are writing that logic. For a single developer poking at one phone, that is fine. For a CI job that runs a hundred times a day across a rack of devices, you are building the orchestration layer yourself, and the README does not describe one.

The third is that the CLI surface is wide. The README highlights device discovery, port forwarding, syslog and oslog streaming, app and profile management, AFC, crash reports, PCAP sniffing, firmware update, recovery and DFU, backup and restore, WebInspector automation, and the CDP bridge. Breadth here is a maintenance surface as much as a feature list. When Apple changes a service, some subset of those commands is affected, and the project's release cadence (three releases in the two days before the last push on 2026-09-24) suggests active churn rather than a frozen interface.

Finally, if you need a supported, vendor-sanctioned path with a compatibility guarantee, this is not it. It is an open reimplementation of undocumented and semi-documented protocols, and it will break when Apple changes them.

How it differs from libimobiledevice and from Xcode's own tooling

libimobiledevice is the obvious comparison, and the README names it as a topic. That project is a C library with a set of small command-line utilities built on top. It is a system dependency: you install it through your package manager, and your own code links against it or shells out to its binaries. It has been the default on Linux for a long time, and it is what many existing scripts already call.

pymobiledevice3 takes the opposite approach. The protocol implementation lives in Python, so there is nothing to link and no ABI to track. You can pip install it in a virtual environment, import the service classes, and step through the parsing in a debugger. The trade-off is performance and reach: a C library can be used from any language, while this is Python-only, and a pure-Python protocol stack is not going to win a throughput contest against compiled code.

The other comparison is Xcode's own instruments and devicectl on macOS. Those are Apple's tools, they are supported, and they only exist on macOS. If your work is macOS-only and you just need to install a build or read a log, they are less effort. pymobiledevice3 earns its place when you need to script the same operations from Linux or Windows, or when you need programmatic access to a service that Apple's CLI does not expose.

Maintenance, release cadence and upgrade risk

The repository is not archived, and the last push was on 2026-09-24. Releases v11.19.0, v11.18.0 and v11.17.2 all landed on 2026-09-23 or 2026-09-24, so the project is moving quickly and version numbers advance in small increments. That cadence cuts both ways: fixes for new iOS builds arrive fast, and so does interface drift.

The upgrade cost is mostly in the dependency graph rather than the CLI. Because pyproject.toml splits construct-typing by Python version, a project that supports both 3.9 and 3.12 is testing two dependency resolutions. The README also ships a Claude Code plugin and an agent skill; those live in .claude-plugin/ and are versioned with the repository, so a pinned install pins the agent instructions too.

For pinning strategy, the honest answer is that the repository does not describe a deprecation policy or an LTS line. There is no documented rollback procedure in the README. If you depend on a specific command's output format, pin the version and read the release notes before bumping, because the release history shows the project is willing to ship several versions in a week.

Editorial conclusion

Adopt pymobiledevice3 if you already write Python and need scripted access to a connected iPhone or iPad: device discovery, AFC file access, syslog streaming, backups, and the DDI/DVT developer tooling that iOS 17 and later require over a tunnel. Do not adopt it if you need a supported, vendor-blessed path, if you cannot accept GPL-3.0 terms in your distribution, or if you are unwilling to manage tunnel and pairing state yourself. Before committing, verify three things on your own hardware: that pip resolves the package on your Python version (3.9 is the floor in pyproject.toml), that pymobiledevice3 usbmux list sees the device, and that your target iOS version appears in the project's own iOS 17+ support matrix, since the README points at that matrix rather than promising blanket coverage.

Frequently asked questions

What is pymobiledevice3?

It is a pure Python 3 implementation for interacting with iOS devices such as iPhone and iPad. It ships a command-line tool and a Python API, and runs on Windows, Linux, and macOS.

How do I install pymobiledevice3 on macOS, Windows or Ubuntu?

The README gives a single command for all three platforms: python3 -m pip install -U pymobiledevice3. Python 3.9 or newer is required according to pyproject.toml, and the docs link an installation page for platform-specific notes.

How do I use pymobiledevice3 after installing it?

Start by confirming the host sees the device with pymobiledevice3 usbmux list. From there the README suggests pymobiledevice3 syslog live to stream logs and pymobiledevice3 apps list to enumerate installed applications.

Is pymobiledevice3 safe to run?

The README does not document a security model or make a safety claim. It states that the project is licensed GPL-3.0-or-later and that it implements lockdown services and developer tooling against a connected device, so it operates with the access your pairing grants it.

Official sources

  1. doronz88/pymobiledevice3 on GitHub
  2. License: GPL-3.0
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/doronz88-pymobiledevice3.svg)](https://hysenlabs.com/projects/doronz88-pymobiledevice3)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/doronz88-pymobiledevice3.svg)](https://hysenlabs.com/projects/doronz88-pymobiledevice3)

Was this useful?