> For the complete documentation index, see [llms.txt](https://docs.drizz.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.drizz.dev/desktop-app/ios-physical-device.md).

# iOS physical device

Real iPhones and iPads are supported from desktop app v1.8.0, on both Apple Silicon and Intel Macs.

{% hint style="info" %}
`Connect Device` → **iOS** → your device → pick your Apple team
{% endhint %}

|                     |                                                                                |
| ------------------- | ------------------------------------------------------------------------------ |
| **Platforms**       | iOS (physical device, from v1.8.0)                                             |
| **Requires**        | Xcode, a USB cable, Developer Mode on the device, an Apple developer team      |
| **Free Apple team** | Profiles expire after **7 days**, and there's a cap on sideloaded apps         |
| **App build**       | Must be a **real-device build** — a simulator build won't install              |
| **Watch out**       | You have to trust the developer certificate on the device before anything runs |

## Prerequisites

* Drizz desktop app v1.8.0 or later, signed in
* Xcode installed and opened once — see [iOS simulator setup](/desktop-app/ios-simulator-setup.md)
* An Apple development team, free or paid
* An iPhone or iPad, unlocked, with a USB cable
* A real-device build of the app under test

## Set up the device

1. Install Xcode on your Mac and open it once. See [iOS simulator setup](/desktop-app/ios-simulator-setup.md).
2. Connect the device by USB.
3. Tap **Trust** when the device asks whether to trust this computer.
4. Enable **Developer Mode** on the device: Settings → Privacy & Security → Developer Mode.
5. Restart the device when prompted. Developer Mode does not take effect until the restart.
6. In Drizz Desktop, open **Connect Device** and select your device.
7. Select your Apple development team in the team picker.
8. Click connect. Drizz signs WebDriverAgent and installs it onto the device.
9. Trust the developer certificate on the device: Settings → General → VPN & Device Management → your certificate → **Trust**.
10. Confirm the device panel shows the device as connected.

Until the certificate is trusted at step 9, iOS refuses to launch anything Drizz installed, and the connection fails with a signing error that does not name the Trust step.

## Apple team types

Drizz labels free and paid teams in the picker and warns when a free team is selected. These limits are Apple's, not Drizz's.

| Limit                         | Free team                                           | Paid team                                 |
| ----------------------------- | --------------------------------------------------- | ----------------------------------------- |
| Provisioning profile lifetime | **7 days**, then re-sign by reconnecting from Drizz | Standard Apple Developer Program duration |
| Sideloaded app cap            | Capped — reached quickly on a shared test device    | Higher                                    |
| Paid-account entitlements     | Unavailable                                         | Available                                 |

## Installing your app

| Rule                                                              | Consequence                                                                                                          |
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| The build must be a real-device build                             | A simulator build will not install on hardware. Drizz names this reason in the error rather than failing generically |
| An App Store copy blocks a sideloaded build of the same bundle ID | iOS will not let a self-signed build replace an App Store install. Uninstall the store version from the device first |

iOS test plans on the Drizz device cloud also require a real-device build.

## Common mistakes

| What you do                                        | What happens                                                                                    |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Skip the Trust step on the device                  | The connection fails with a signing error. Settings → General → VPN & Device Management → Trust |
| Enable Developer Mode but not restart              | Developer Mode doesn't take effect until the restart                                            |
| Use a simulator build on hardware                  | It won't install. Drizz names the reason — build for a real device                              |
| Sideload over an App Store install of the same app | Blocked by iOS. Uninstall the store version first                                               |
| Use a free Apple team for an ongoing suite         | It breaks every 7 days when the profile expires. Use a paid account                             |
| Unplug the device mid-run                          | The session dies. Keep it connected and unlocked for the whole run                              |
| Leave the device locked                            | Drizz checks lock state and refuses a locked device                                             |

## Next

* [iOS simulator setup](/desktop-app/ios-simulator-setup.md)
* [Real Android device](/desktop-app/android-real-device.md)
* [Report an issue](/desktop-app/report-an-issue.md)

***

*Last updated: 6 August 2026*