Fix: Can’t Install a .ipa File on the iOS Simulator

Why this happens

An .ipa is just a zip archive with a Payload folder inside, and inside that folder sits a .app bundle. The bundle was compiled against the iOS device SDK for a physical iPhone or iPad. The Simulator is a different platform: it runs your code against the iOS Simulator SDK on your Mac’s CPU, not against the device runtime. A binary built for the device platform will not load in the Simulator, no matter how you copy it in.

There is a second blocker for anything downloaded from the App Store. Those binaries are encrypted with FairPlay. The decryption key lives on the device that purchased the app, so even the Mach-O header is unreadable off-device. Extracting the bundle gives you a file you cannot execute anywhere except a real iPhone.

So the short answer to “how do I install this .ipa on the Simulator” is: you don’t. You install a Simulator build instead, and that build is a .app, not an .ipa.

How to fix it

1. Build for a Simulator destination and install the .app

This is the only supported path, and it requires the project source.

1. Open the project in Xcode and pick any iOS Simulator from the scheme’s destination menu (for example iPhone 17 Pro).
2. Build with Product > Build (⌘B).
3. The product lands in Derived Data under Build/Products/Debug-iphonesimulator/. You can jump straight there with Product > Show Build Folder in Finder.
4. Boot a Simulator, then install the bundle:

# See which simulator is currently running
xcrun simctl list devices booted

# Install the simulator build
xcrun simctl install booted \
  ~/Library/Developer/Xcode/DerivedData/MyApp-*/Build/Products/Debug-iphonesimulator/MyApp.app

# Launch it by bundle identifier
xcrun simctl launch booted com.example.MyApp

If you prefer the mouse: boot the Simulator, then drag the .app bundle from Finder onto the Simulator window. It installs and appears on the Home Screen. Dragging an .ipa does nothing useful.

2. If you only have the .ipa, get a Simulator build from the developer

A .ipa is a distribution artifact. It is produced for Ad Hoc, Enterprise, Development or App Store delivery, and every one of those targets real hardware. Ask the developer for one of these instead:

• The Xcode project or workspace, so you can build for the Simulator yourself.
• A prebuilt .app compiled with a Simulator destination (they can zip the Debug-iphonesimulator product and send it).
• A TestFlight or Ad Hoc build, if you actually have a physical device to test on.

There is no conversion step that turns a device .ipa into a Simulator app. The two builds differ at link time, not at packaging time.

3. Why the old “unzip and copy into the SDK” trick no longer works

The widely repeated workaround was: rename the .ipa to .zip, extract it, take Payload/AppName.app, and copy it into a folder like Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/SDKs/iPhoneSimulator6.0.sdk/Applications/.

That path belonged to Xcode 4-era Simulator runtimes. Modern Xcode ships Simulator runtimes as separate installable packages, and each simulated device has its own data container managed by CoreSimulator. There is no shared Applications folder inside the SDK to drop bundles into, and hand-copying into a runtime’s filesystem is not a supported install path.

Even if the bundle did land somewhere the Simulator scans, it would still be a device build. The install is rejected, or the app installs and dies on launch because the dynamic loader cannot resolve the device-platform binary.

You can confirm what you are holding before wasting time:

# Unpack the archive
unzip -q MyApp.ipa -d MyAppExtracted

# Check which platform the Mach-O was built for
vtool -show-build MyAppExtracted/Payload/MyApp.app/MyApp

The output includes a platform line. IOS means device only. IOSSIMULATOR means it will run in the Simulator. That single line tells you whether the bundle is usable before you try to install it.

4. Use a real device when the .ipa is all you have

If the goal is simply to run someone else’s build, the Simulator is the wrong tool. Install the .ipa on a registered device through one of the normal channels:

• TestFlight — the developer uploads a build to App Store Connect and invites you.
• Ad Hoc — your device UDID is included in the provisioning profile.
• Development build — installed from Xcode with a development team selected.

All of these need a signed-in Apple Developer account and a device that the profile covers.

How to prevent it

• Keep the two products straight: .ipa means device, .app from Debug-iphonesimulator means Simulator.
• Never circulate .ipa files for Simulator testing — send the project or a Simulator .app instead.
• Run vtool -show-build on any bundle of unknown origin before trying to install it.
• Use xcrun simctl install booted in scripts rather than copying files into runtime folders by hand.
• Remember that Apple Silicon does not blur the line: Simulator binaries are arm64 too, but they still target the Simulator platform, not iOS.

FAQ

Can I install an .ipa through Xcode’s Devices and Simulators window?

No. That window manages physical devices and Simulator runtime downloads. Simulator apps are installed with xcrun simctl install or by dragging the .app onto the running Simulator.

Does an Apple Silicon Mac make device builds compatible with the Simulator?

No. Both may be arm64, but the binary is linked against the iOS device SDK and carries the device platform in its load commands. The Simulator only loads binaries built for the Simulator platform.

Can I convert an .ipa into a Simulator app?

Not meaningfully. Unzipping gives you the .app bundle, but the executable inside is still a device build, and App Store copies are additionally FairPlay-encrypted. You need a build produced with a Simulator destination.