Skip to content

Run your iOS app on the simulator or a device

This page shows you how to build and launch your app on the iOS Simulator, which needs no signing, and on a connected iPhone or iPad, which does.

Before you begin

Run on the Simulator

  1. Build, install, and launch the app:

    kivyforge run -p ios --simulator

    --simulator is the default target for run, so you can omit it. run builds the app, boots a Simulator if none is running, installs the app, and launches it.

  2. Optional: to target a specific Simulator, list the available simulators and devices, then pass a name or UDID (unique device identifier) with --destination:

    kivyforge run -p ios --list-devices
kivyforge run -p ios --simulator --destination "DEVICE_NAME"

    Replace DEVICE_NAME with a simulator name or UDID from the list.

Iterate on Python source

For development builds, the generated project links your app_dir through a symbolic link. After you edit Python source, pressing Run in Xcode picks up the change without rerunning kivyforge. Run kivyforge build again when you change pyproject.toml.

Run on a device

  1. Set up signing. See Sign your iOS app.

  2. Connect the device, then build, sign, install, and launch the app:

    kivyforge run -p ios --device

    To choose between several connected devices, pass --destination with a device name or UDID from kivyforge run -p ios --list-devices.

run streams the app's console to your terminal until the app ends. To end it on the device, close it from the app switcher; going to the Home Screen only suspends it. iOS often ends a closed app with SIGKILL, which devicectl reports as "App terminated due to signal 9.", so run then exits with an error even though the app ran normally. Pressing Ctrl+C in the terminal stops run instead.

To install an app you already built, add --no-build.

Build without running

  • kivyforge build -p ios --simulator or kivyforge build -p ios --device builds the .app without installing it.
  • kivyforge build -p ios with no target stops after generating the Xcode project, ready to open in Xcode.

Verify

The app window appears in the Simulator or on the device. To get the path of the built .app, run a build command with --json and read data.artifacts:

kivyforge build -p ios --simulator --json

What's next