Using tidevice for iOS Automation without a Mac: Features, Installation, and Integration Guide

Introduction

iOS automation has traditionally required a macOS environment because Xcode must compile and install WebDriverAgent (WDA) on the device. This limitation forces non‑Mac users to acquire Mac hardware, leading to under‑utilized resources and high costs for cloud testing platforms.

Alibaba’s open‑source project tidevice ( https://github.com/alibaba/taobao-iphone-device) removes the macOS dependency, allowing developers to perform iOS automation from any platform.

What tidevice Can Do

Retrieve device information.

Install, uninstall, launch, stop, and query apps, including listing installed apps.

Start WebDriverAgent without Xcode (cross‑platform).

Run XCTest UI tests.

Collect performance data such as FPS.

Take screenshots and fetch device logs.

Core Principle

usbmux Communication Protocol

tidevice uses the usbmux protocol to communicate between a host (Mac/Windows/Linux) and an iOS device. macOS provides the native usbmuxd service; on Windows and Linux, open‑source implementations are used, sometimes requiring AppleApplicationSupport and AppleMobileDeviceSupport.

The protocol is essentially a TCP‑like socket over USB, which tidevice simulates with Python to implement all its features.

Installation

Python 3.6+ is required.

Install tidevice: pip3 install -U "tidevice[openssl]" (recommended) or pip3 install -U tidevice (without pairing support).

Install usbmuxd: macOS: built‑in at /var/run/usbmux. Linux/Windows: follow the instructions at https://github.com/alibaba/taobao-iphone-device/issues/7.

Command‑Line and Python Interfaces

All tidevice commands are defined in tidevice.__main__. The following sections show representative commands and their equivalent Python code.

Device Management

List Connected Devices

Command: tidevice list Python:

from tidevice import Usbmux
print(Usbmux().device_list())

Watch Device Connection Events

Command: tidevice watch Python:

from tidevice import Usbmux
for info in Usbmux().watch_device():
    print(info)

Note: Usbmux().watch_device() returns a generator that blocks the main thread; using a separate process is recommended.

Wait for Any Device

Command: tidevice wait‑for‑device Python:

from tidevice import Usbmux
for info in Usbmux().watch_device():
    if info["MessageType"] == "Attached":
        break

Wait for a Specific Device

Command: tidevice -u $UDID wait‑for‑device Python:

from tidevice import Usbmux
for info in Usbmux().watch_device():
    if info["MessageType"] != "Attached":
        continue
    udid = info["Properties"]["SerialNumber"]
    if udid == "$UDID":
        break

Print Device Logs

Command: tidevice -u $UDID syslog Python:

from tidevice import Device
 d = Device("udid")
 d.start_service("com.apple.syslog_relay")
 while True:
     print(s.recv().decode("utf-8"))

App Management

Install an App

Command: tidevice --udid $UDID install example.ipa Python:

from tidevice import Device
 Device("udid").app_install("example.ipa")

Uninstall an App

Command: tidevice --udid $UDID uninstall com.example.demo Python:

from tidevice import Device
 Device("udid").app_uninstall("com.example.demo")

Launch an App

Command: tidedevice --udid $UDID launch com.example.demo Python:

from tidevice import Device
 pid = Device("udid").app_start("com.example.demo")
 # Force restart
 pid = Device("udid").app_start("com.example.demo", kill_running=True)

Stop an App

Command: tidevice --udid $UDID kill com.example.demo Python:

from tidevice import Device
 Device("udid").app_stop(pid_or_name)

List Installed Apps

Command: tidevice --udid $UDID applist Python:

from tidevice import Device
 instruments = Device("udid").connect_instruments()
 apps = instruments.app_list()
 user_apps = [app for app in apps if app["Type"] == "User"]

Get App Information

Command: tidevice appinfo com.example.demo Python:

from tidevice import Device
 Device("udid").installation.lookup("com.example.demo")

Parse IPA (URL or File)

Command: tidevice parse ipa_url Python (URL):

import httpio
 from tidevice._ipautil import IPAReader
 fp = httpio.open(url, block_size=1)
 ir = IPAReader(fp)
 ir.get_infoplist()

Python (File):

from tidevice._ipautil import IPAReader
 fp = open("path/to.ipa", "rb")
 ir = IPAReader(fp)
 ir.get_infoplist()

Automation Execution

Run XCTest

Command: tidevice xctest -B com.facebook.wda.WebDriverAgent.Runner Python:

from tidevice import Device
 Device("udid").xctest("com.facebook.wda.WebDriverAgent.Runner")

Running XCTest blocks subsequent operations; using a separate process is advised.

Run XCTest with Custom Port and Debug Logging

Command:

idevice XCTestCase -B com.facebook.wda.WebDriverAgent.Runner -e USB_PORT:8200 --debug

Python:

from tidevice import Device
 import logging
 logger = logging.getLogger("tidevice.xctest")
 Device("udid").xctest("com.facebook.wda.WebDriverAgent.Runner", log=logger, evn={"USB_PORT": 8200})

Relay (Port Forwarding)

Command: tidedevice relay 8100 8100 Python:

from tidevice import Device
 from tidevice._relay import relay
 d = Device("udid")
 relay(d, 8100, 8100)

Debug mode (hex dump): tidedevice relay -x 8100 8100 Python debug:

relay(d, 8100, 8100, debug=True)

WDA Proxy

Command:

tidedevice wdaproxy -B com.facebook.wda.WebDriverAgent.Runner --port 8200

Python (method 1):

from tidevice._wdaproxy import WDAService
 from tidevice import Device
 d = Device("udid")
 serv = WDAService(d, "com.facebook.wda.WebDriverAgent.Runner")
 # start subprocess that runs relay 8200->8100
 # then serv.start() … serv.stop()

Python (method 2 – combine xctest and relay with multiprocessing):

from tidevice import Device
 from tidevice._relay import relay
 from multiprocessing import Process
 d = Device("udid")
 p1 = Process(target=d.xctest, args=("com.facebook.wda.WebDriverAgent.Runner", None, None, {"USB_PORT": 8200}))
 p2 = Process(target=relay, args=(d, 8200, 8100, False))
 p1.start(); p2.start()
 # … later terminate both processes

Device Information

Basic Info

Command: tidedevice info Python:

from tidevice import Device
 Device("udid").device_info()

Battery Info

Command: tidedevice info --domain com.apple.mobile.battery --json Python:

from tidevice import Device
 import json
 info = Device("udid").device_info("com.apple.mobile.battery")
 print(json.dumps(info))

System Info

Command: tidedevice sysinfo Python:

from tidevice import Device
 Device("udid").instruments.system_info()

FPS Data

Command: tidedevice dumpsfps Python:

from tidevice import Device
 d = Device("udid")
 for data in d.instruments.iter_opengl_data():
     if isinstance(data, str):
         continue
     print(data["CoreAnimationFranesPerSecond"])

Device Operations

Screenshot

Command: tidedevice screenshot Python (save to timestamped file):

from tidevice import Device
 import time
 filename = "screenshot_" + str(time.time()) + ".jpg"
 Device("udid").screenshot().conver("RGB").save(filename)

Shutdown / Reboot

Command: tidedevice shutdown / tidedevice reboot Python:

from tidevice import Device
 Device("udid").shutdown()
 Device("udid").reboot()

File Sync

Command: tidedevice -u $UDID fsync Python:

from tidevice import Device
 Device("udid").sync

App File Sync

Command: tidedevice -u $UDID fsync -B com.example.app Python:

from tidevice import Device
 Device("udid").app_sync("com.example.app")

Pair Device

Command: tidedevice -u $UDID pair Python:

from tidevice import Device
 Device("udid").pair()

Integration Guidance

The typical workflow uses Appium as the test framework. Before launching the Appium driver, tidevice can start WDA and forward ports (wdaproxy). The local port must be recorded and injected into the driver capabilities as webDriverAgentUrl. After tests finish, ensure tidevice processes are terminated.

Recommendations

If you still have a macOS pipeline, keep it as a fallback because tidevice’s wdaproxy may occasionally experience communication issues.

When integrating on non‑macOS platforms, add logic to detect the host OS and choose the appropriate tidevice commands.

Conclusion

tidevice frees iOS automation from the macOS constraint, opening new possibilities for cross‑platform test infrastructures. Windows users can start WDA via wdaproxy and drive tests with Appium. Linux servers can host remote iOS automation using tidevice. Performance data collection is possible on macOS, Windows, and Linux. Because tidevice only uses a subset of the underlying usbmux code, developers can extend it further by reading the source. Thanks to the Alibaba team for open‑sourcing tidevice; we hope this guide helps you get started. Give it a try, integrate it, and explore the source! If you liked this article, please follow, share, like, comment, or tip.