Skip to content

physical_device_install

Install a compiled .app bundle onto a connected physical iOS device. This tool pushes the application binary to the device and installs it, similar to what Xcode does when you click Run targeting a physical device. The app must be properly code-signed for the target device.

Parameters

Parameter	Type	Required	Default	Description
`deviceId`	string	Yes	—	The UDID of the target device (obtain from `physical_device_list`)
`appPath`	string	Yes	—	Absolute path to the `.app` bundle to install

Usage Examples

Install a debug build on iPhone

“Install FitnessTracker on my iPhone 15 Pro Max”

{
  "deviceId": "00008130-001A2B3C4D5E6F78",
  "appPath": "/Users/dev/Library/Developer/Xcode/DerivedData/FitnessTracker-abc123/Build/Products/Debug-iphoneos/FitnessTracker.app"
}

Install on an iPad over Wi-Fi

“Deploy the latest build to my iPad Air”

{
  "deviceId": "00008103-000A1B2C3D4E5F60",
  "appPath": "/Users/dev/Library/Developer/Xcode/DerivedData/FitnessTracker-abc123/Build/Products/Debug-iphoneos/FitnessTracker.app"
}

Install a release build from an archive

“Install the archived release build on my test device”

{
  "deviceId": "00008110-001122334455AABB",
  "appPath": "/Users/dev/Library/Developer/Xcode/Archives/2025-01-15/FitnessTracker.xcarchive/Products/Applications/FitnessTracker.app"
}

Example Output

Installing app on device...

Device:      iPhone 15 Pro Max (00008130-001A2B3C4D5E6F78)
App:         FitnessTracker.app
Bundle ID:   com.acmecorp.fitnesstracker

Progress:
  Copying app to device...    done
  Verifying code signature... done
  Installing app...           done

App installed successfully. Use physical_device_launch to start the app.

When installation fails:

Installing app on device...

Device:      iPhone 15 Pro Max (00008130-001A2B3C4D5E6F78)
App:         FitnessTracker.app
Bundle ID:   com.acmecorp.fitnesstracker

Error: Installation failed.
  The code signature is not valid for this device. The provisioning profile
  "iOS Team Provisioning Profile: com.acmecorp.fitnesstracker" does not
  include this device's UDID.

  Add device UDID 00008130-001A2B3C4D5E6F78 to your provisioning profile
  in the Apple Developer portal and re-sign the app.

physical_device_list — List connected devices to find the target UDID
physical_device_launch — Launch the app after installation
physical_device_console — Stream logs from the device after launching
xcode_build — Build the app for a physical device before installing

Tips