Metadata-Version: 2.4
Name: pymobiledevice3
Version: 9.12.3
Summary: Pure python3 implementation for working with iDevices (iPhone, etc...)
Author-email: doronz88 <doron88@gmail.com>, matan <matan1008@gmail.com>
Maintainer-email: doronz88 <doron88@gmail.com>, matan <matan1008@gmail.com>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/doronz88/pymobiledevice3
Project-URL: Bug Reports, https://github.com/doronz88/pymobiledevice3/issues
Keywords: ios,protocol,lockdownd,instruments,automation,cli,afc
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: construct>=2.9.29
Requires-Dist: construct-typing>=0.7.0
Requires-Dist: asn1
Requires-Dist: coloredlogs
Requires-Dist: IPython
Requires-Dist: bpylist2>=4.0.1
Requires-Dist: pygments
Requires-Dist: hexdump
Requires-Dist: daemonize
Requires-Dist: gpxpy!=1.6.0,<1.7.0
Requires-Dist: pykdebugparser>=1.2.7
Requires-Dist: pyusb>=1.2.1
Requires-Dist: tqdm
Requires-Dist: requests
Requires-Dist: xonsh
Requires-Dist: parameter_decorators
Requires-Dist: packaging
Requires-Dist: pygnuutils>=0.0.7
Requires-Dist: cryptography>=41.0.1
Requires-Dist: pycrashreport>=2.0.0
Requires-Dist: fastapi>=0.93.0
Requires-Dist: uvicorn>=0.15.0
Requires-Dist: wsproto
Requires-Dist: Pillow
Requires-Dist: inquirer3>=0.6.0
Requires-Dist: ipsw_parser>=1.6.0
Requires-Dist: ifaddr
Requires-Dist: hyperframe
Requires-Dist: srptools
Requires-Dist: qh3<2,>=1.0.0
Requires-Dist: developer_disk_image>=0.0.2
Requires-Dist: opack2
Requires-Dist: psutil
Requires-Dist: pytun-pmd3>=3.0.3
Requires-Dist: prompt_toolkit
Requires-Dist: sslpsk-pmd3>=1.0.3; python_version < "3.13"
Requires-Dist: python-pcapng>=2.1.1
Requires-Dist: plumbum
Requires-Dist: pyimg4>=0.8.8
Requires-Dist: typer>=0.20.0
Requires-Dist: typer-injector>=0.2.0
Requires-Dist: defusedxml
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-asyncio; extra == "test"
Provides-Extra: full
Requires-Dist: defusedxml; extra == "full"
Requires-Dist: pytest; extra == "full"
Dynamic: license-file

# PyMobileDevice3

<!-- markdownlint-disable MD013 -->
[![Python application](https://github.com/doronz88/pymobiledevice3/workflows/Python%20application/badge.svg)](https://github.com/doronz88/pymobiledevice3/actions/workflows/python-app.yml "Python application action")
[![Pypi version](https://img.shields.io/pypi/v/pymobiledevice3.svg)](https://pypi.org/project/pymobiledevice3/ "PyPi package")
[![Downloads](https://static.pepy.tech/personalized-badge/pymobiledevice3?period=total&units=none&left_color=grey&right_color=blue&left_text=Downloads)](https://pepy.tech/project/pymobiledevice3)
[![Discord](https://img.shields.io/discord/1133265168051208214?logo=Discord&label=Discord)](https://discord.gg/52mZGC3JXJ)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/doronz88/pymobiledevice3)
<!-- markdownlint-enable MD013 -->

## Overview

`pymobiledevice3` is a pure Python 3 implementation for interacting with iOS devices (iPhone, iPad, ...).
It includes both a CLI and a Python API and is supported on:

- Windows
- Linux
- macOS

Main features:

- Device discovery over bonjour
- TCP port forwarding
- Syslog and oslog streaming
- Profile and application management
- AFC file access
- Crash report collection
- Network sniffing (PCAP)
- Firmware update
- Recovery/DFU workflows
- Notification listen/post (`notify_post()`)
- Querying and setting SpringBoard options
- WebInspector automation
- DDI/DVT developer tooling
- Backup and restore

## Quick Start

Install from PyPI:

```shell
python3 -m pip install -U pymobiledevice3
```

Or install from source:

```shell
git clone git@github.com:doronz88/pymobiledevice3.git
cd pymobiledevice3
python3 -m pip install -U -e .
```

Verify connectivity and run first commands:

```shell
pymobiledevice3 usbmux list
pymobiledevice3 syslog live
pymobiledevice3 apps list
```

## Platform Notes

- Windows:
  - Install iTunes from Microsoft Store:
    <https://apps.microsoft.com/detail/9pb2mz1zmb1s?hl=en-US&gl=US>
  - For WSL2, enable mirrored networking mode:
    <https://learn.microsoft.com/en-us/windows/wsl/networking#mirrored-mode-networking>

    ```none
    [wsl2]
    networkingMode=mirrored
    ```

- Linux:
  - Install `usbmuxd`: <https://github.com/libimobiledevice/usbmuxd>

- OpenSSL:
  - OpenSSL is explicitly required for older iOS versions (`< 13`).

- Recovery/DFU support
  - Requires `libusb`.

### Support Matrix (Developer Services)

`iOS >= 17` developer services require tunnel-based transport.

| Host OS | iOS 17.0-17.3.1 | iOS 17.4+ |
| --- | --- | --- |
| macOS | Supported | Supported |
| Windows | Supported (requires additional drivers) | Supported |
| Linux | Limited | Supported (lockdown tunnel) |

See the detailed guide: [iOS 17+ tunnels](docs/guides/ios17-tunnels.md)

## Common CLI Tasks

See full recipes: [CLI recipes](docs/guides/cli-recipes.md)

```shell
# List connected devices
pymobiledevice3 usbmux list

# Watch syslog
pymobiledevice3 syslog live

# Pull crash reports
pymobiledevice3 crash pull /path/to/crashes

# Mount DDI
pymobiledevice3 mounter auto-mount

# DVT screenshot (requires developer setup)
pymobiledevice3 developer dvt screenshot /path/to/screen.png
```

Install shell completions:

```shell
pymobiledevice3 install-completions
```

## Python API and Protocol Internals

- Protocol overview:
  [Understanding iDevice protocol layers](misc/understanding_idevice_protocol_layers.md)
- DTX API quick start:
  [DTX README](pymobiledevice3/dtx/README.md)
- DTX internals:
  [DTX DEVELOPMENT](pymobiledevice3/dtx/DEVELOPMENT.md)
- RemoteXPC internals:
  [RemoteXPC](misc/RemoteXPC.md)
- Building custom CLI commands with `service_provider`:
  [Guide](docs/guides/writing-commands-with-service-provider.md)

## Documentation Map

See [Documentation index](docs/README.md) for task-focused guides.

## Contributing

See [CONTRIBUTING](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md).
Agent-specific contributor guidance is in [AGENTS](AGENTS.md).

## License and Credits

This work is licensed under GPL 3.0 and credited to several major contributors:

- Hector Martin "marcan" <hector@marcansoft.com>
- Mathieu Renard
- [doronz](https://github.com/doronz88) <doron88@gmail.com>
- [matan1008](https://github.com/matan1008) <matan1008@gmail.com>
- [Guy Salton](https://github.com/guysalt)
- [netanelc305](https://github.com/netanelc305) <netanelc305@protonmail.com>
- Inbar Agmon <inbar2812@gmail.com> ([Project's logo](https://repository-images.githubusercontent.com/357904774/6d6fb035-5953-425d-9afd-cc1087df0cfb))
