with Fast Refresh, the fastest way to iterate on UI. Flags:

`--width`, `--height`, `--title`, `--no-hot-reload`. See the

[Desktop preview guide](../guides/desktop-preview.md).

- `pn devices [android|ios]`: list connected devices, emulators, and

simulators with the identifiers `--device` accepts.

- `pn run android|ios`: build and run on a connected device or

simulator. Flags: `--device` (target a specific device by identifier

or name), `--prepare-only`, `--hot-reload`, `--no-logs`.

- `pn logs android|ios`: stream logs from the running app without

rebuilding.

- `pn build android|ios`: build distributable artifacts (release by

default). Flags: `--debug` for the debug variant, `--upload` to send

an iOS release build to App Store Connect. See

[Building for release](../guides/building-for-release.md).

- `pn app-id android|ios`: print the resolved application id (Android)

or bundle id (iOS), handy for scripts and CI.

- The iOS template (Swift with CPython embedded through the C API) boots Python and calls

[`create_screen`][pythonnative.create_screen] internally with the

current `UIViewController` pointer.

- The reconciler creates UIKit views and attaches them to the

pn run android

With several devices or emulators connected, list them and target one:

pn devices android

pn run android --device emulator-5554

Or to only prepare the project without building:

Press Ctrl+C to stop streaming. Pass `--no-logs` to skip log streaming

entirely (useful in CI or when you'd rather watch logs from Android Studio).

To re-attach later without rebuilding, run `pn logs android`.

If you need unfiltered output, run `adb logcat` yourself in another terminal.

`pn build ios` archives the app with `xcodebuild archive` and exports a

signed `.ipa` with `xcodebuild -exportArchive`. The Python framework,

standard library, and app code are installed and signed during the

Xcode build itself, so the archive needs no post-processing. Outputs:

To send the build straight to App Store Connect instead of exporting a

local `.ipa`, set `export_method = "app-store"` and pass `--upload`:

pn build ios --upload

The upload uses the App Store Connect credentials Xcode has stored; in

CI, provide an ASC API key through Xcode's standard mechanisms or

upload the exported `.ipa` with `xcrun altool`/Transporter instead.

Release builds byte-compile your `app/` sources and every bundled

package to `.pyc` and drop the `.py` files, which shrinks the bundle

and avoids shipping plain-text source. Because bytecode is

version-specific, this requires the Python running `pn` to match

`app.python_version`; otherwise `pn` prints a notice and ships `.py`

sources instead.

[Python-Apple-support](https://github.com/beeware/Python-Apple-support)

project. On the first iOS build, `pn` downloads the pinned, checksum-

verified runtime for your `app.python_version` and caches it under

`build/ios/ios_runtime/`. The Xcode build links `Python.xcframework`,

installs the standard library, and bundles your `app/` sources, the

`pythonnative` package, and any pure-Python `[requirements].packages`.

Pinned, verified runtimes exist for **Python 3.10, 3.11, and 3.12**;

set `python_version` in `[app]` accordingly. Unpinned versions are

rejected rather than fetched unverified.

python_version = "3.11" # embedded CPython version

orientation = "portrait" # portrait | landscape | all

entry_point = "app/main.py" # module whose `App` is mounted

url_schemes = ["myapp"] # deep-link schemes the app handles

[permissions]

camera = "Scan receipts with your camera."

[android]

min_sdk = 24

target_sdk = 34

[android.signing]

| `display_name` | string | `name` | The label shown under the icon on the home screen. |

| `version` | string | `"1.0.0"` | Marketing version (`CFBundleShortVersionString` / `versionName`). One to four dot-separated numbers. |

| `build` | integer | `1` | Build number (`CFBundleVersion` / `versionCode`). Must be a positive integer; bump it for every store upload. |

| `python_version` | string | `"3.11"` | Embedded CPython version. One of `3.10`, `3.11`, `3.12`; every listed version has a pinned, checksum-verified iOS runtime. |

| `orientation` | string | `"portrait"` | `portrait`, `landscape`, or `all`. |

| `url_schemes` | list of strings | `[]` | Custom deep-link URL schemes (e.g. `["myapp"]` handles `myapp://…`). Wired into `CFBundleURLTypes` on iOS and a `VIEW` intent filter on Android; inbound URLs reach `pn.Linking`. |

| `entry_point` | string | `"app/main.py"` | The module whose top-level `App` component is mounted. `app/main.py` → imported as `app.main`. |

!!! tip "Per-platform id overrides"

| `target_sdk` | integer | `34` | Target API level. Must be ≥ `min_sdk`. |

| `compile_sdk` | integer | `34` | SDK level the project compiles against. |

| `application_id` | string | `app.id` | Override the Android application id (and package). |

| `abi_filters` | list of strings | `["arm64-v8a", "x86_64"]` | Native ABIs to include. The default covers 64-bit devices and emulators; add `armeabi-v7a` or `x86` only if you must support 32-bit hardware (each ABI adds roughly 30 MB). |

| `permissions` | list of strings | `[]` | Extra **raw** Android permission strings appended to the ones derived from `[permissions]`. |

`pn run ios` unpacks the bundled iOS template (a Swift Xcode project) into `build/ios/ios_template` and stages three things at the project root:

- `Python.xcframework`: the embedded CPython runtime for your `app.python_version` (downloaded once, checksum-verified, and cached under `build/ios/ios_runtime/`).

- `app/`: your project's Python sources.

- `app_packages/`: the `pythonnative` package, `rubicon-objc`, and any `[requirements].packages`.

The Xcode project links the framework at build time and embeds CPython through its C API (`PythonRuntime.swift`); an "Install Python runtime" build phase installs the standard library and converts binary modules into signed frameworks. The built `.app` is therefore complete as soon as `xcodebuild` finishes, with no post-build patching. If Python fails to start or your root component fails to mount, the app shows a full-screen error report with the Python traceback instead of failing silently.

pn run ios

To target a specific Simulator, or a physical device, list the available targets and pass one to `--device`:

pn devices ios

pn run ios --device "iPhone 15 Pro"

pn run ios --device 00008120-001234567890ABCD

Running on a physical device requires `[ios].development_team` in `pythonnative.toml` (for code signing), a paired device, and Developer Mode enabled on the device (Settings > Privacy & Security > Developer Mode).

Or prepare without building:

a non-interactive context like CI (see the `e2e.yml` workflow for an

example).

To re-attach to a running app later without rebuilding, use:

pn logs ios

For a physical device, use Console.app or Xcode's Devices and

Simulators window; `simctl` console attach is Simulator-only.

- **Xcode 14 or newer.** `simctl launch --console-pty` was added in

`request_permission()` is required on iOS and on Android 13+. On

older Android the call returns `True` without prompting.

For server-sent (remote) pushes, declare the `remote_notifications`

capability in `pythonnative.toml`, then register with APNs:

token = await pn.Notifications.get_device_token() # APNs hex token

Your server passes the token to APNs to address this install. The

simulator has no APNs connection, so test on a real device. Android

remote push requires Firebase Cloud Messaging, which the built-in

module doesn't wire up; `get_device_token()` returns `None` there.

[`Clipboard`][pythonnative.Clipboard] reads and writes the system

[`Linking`][pythonnative.Linking] opens URLs, deep links, and the app's

Settings page, and delivers inbound deep links to your app.

if pn.Linking.can_open_url("tel:+15551234567"):

pn.Linking.open_settings() # this app's entry in Settings

To receive deep links, declare your schemes in `pythonnative.toml`:

[app]

url_schemes = ["myapp"]

Opening `myapp://orders/42` now launches (or foregrounds) your app on

both platforms. The URL that cold-started the app is returned by

`get_initial_url()`; URLs that arrive while the app is running reach

subscribers:

unsubscribe = pn.Linking.add_listener(lambda url: navigate_to(url))

[`Permissions`][pythonnative.Permissions] normalizes the iOS/Android

| `face_id` | Biometric auth | `NSFaceIDUsageDescription` | `USE_BIOMETRIC` |

| `bluetooth` | Nearby Bluetooth devices | `NSBluetoothAlwaysUsageDescription` | `BLUETOOTH_CONNECT`, `BLUETOOTH_SCAN` |

| `speech_recognition` | Speech recognition (iOS) | `NSSpeechRecognitionUsageDescription` | – |

| `notifications` | Show local notifications | – | `POST_NOTIFICATIONS` |

| `remote_notifications` | Server-sent (remote) push | – (adds the `aps-environment` entitlement and `remote-notification` background mode) | `POST_NOTIFICATIONS` |

| `vibration` | Haptics / vibration | – | `VIBRATE` |

| `background_audio` | Play audio in background | – (adds `audio` background mode) | `FOREGROUND_SERVICE` |

| `background_fetch` | Periodic background fetch | – (adds `fetch` background mode) | – |

`location_always`, `background_audio`, `background_fetch`, and

`remote_notifications` also add the corresponding values to the iOS

`UIBackgroundModes` array (`location`, `audio`, `fetch`,

`remote-notification`) so the OS keeps your app scheduled.

Some capabilities need a code-signing entitlement rather than an

`Info.plist` key. Declaring `remote_notifications` generates an

`.entitlements` file with `aps-environment` and wires it into the

build, so `await pn.Notifications.get_device_token()` can register with

APNs. (Distribution builds get the production APNs environment

automatically when Xcode re-signs the archive for the store.)