Create an iOS simulator build

Testing on simulators requires an .app file (not an .ipa file). This is a restriction imposed by Apple.

Applications compiled exclusively for Intel (x86_64) cannot run on iOS 26.4 or later simulators. An ARM64 build is required.

You can generate an app build for testing on a simulator either through the command line or through XCode. This article provides information on both options.

  1. Open a command line window and go to the app directory.

  2. To build the XCode project and generate the build, run the following command:

    Copy 
    xcodebuild -sdk iphonesimulator

    If the application is developed in a workspace, that is if the project directory includes a .xcworkspace file, use the following command instead:

    xcodebuild -workspace Example.xcworkspace -scheme Example -sdk iphonesimulator

  3. When a success message appears at the end of the command, you can access the build at the following location:

    ~/Library/Developer/Xcode/DerivedData

    The app is located in the following directory:

    ~/Library/Developer/Xcode/DerivedData/Example/Build/Products/Release-iphonesimulator/Example.app

Command options

The xcodebuild command has multiple options, such as scheme, target, and architecture. Make sure to use the correct scheme to generate the expected build. You can run the xcodebuild -list command to view all available schemes, targets, and architectures. 

Following are examples of how you can override the default settings:

  • -derivedDataPath

    This option lets you specify a directory for the build products. For example, if you run the following command, the app resides at ./build/Build/Products/Debug-iphonesimulator/Example.app instead of in the default directory.

    Copy
    Example: -derivedDataPath
    xcodebuild -scheme Example -sdk iphonesimulator -derivedDataPath build

  • -destination

    This option lets you build for a specific device. For example, if you run the following command, the app built is intended for iPhone 11 with iOS 13.3.

    Copy
    Example: -destination
    xcodebuild -sdk iphonesimulator -destination 'platform=iOS Simulator,name=iPhone 11,OS=13.3'

  • -arch

    This option lets you build for multiple architectures by creating a universal binary that supports both Intel-based and Apple Silicon-based Mac machines. For more information, see Apple's article Building a Universal macOS Binary.

    Copy
    Example: -arch
    xcodebuild -sdk iphonesimulator -arch 'x86_64' -arch 'arm64'

For additional information on the various build actions and how to use the command, you can run the following commands or see Apple's Building from the Command Line with Xcode FAQ:

  • man xcodebuild
  • xcodebuild -help
  1. Open the app in Xcode. 
  2. Build the application with the simulator target.
  3. When the build has completed successfully, in the file navigator, right-click the Products folder and select Show in Finder. This opens the folder with the simulator build.