Every PythonNative project is described by a single pythonnative.toml file at its root. It is the one source of truth for your app's identity (bundle/application id, name, version), the device permissions it requests, its icon and splash, the packages it bundles, and signing. pn init scaffolds one for you, and every other command (pn run, pn build, pn doctor, pn app-id) reads it.

[app]
id = "com.example.myapp"        # reverse-DNS id (required)
name = "myapp"                  # short project name (required)
display_name = "My App"         # home-screen label (defaults to name)
version = "1.0.0"               # marketing version
build = 1                       # integer build number
python_version = "3.13"         # embedded CPython version (3.13 or 3.14)
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."
location_when_in_use = "Show nearby stores."
notifications = true

[assets]
icon = "assets/icon.png"        # 1024x1024 source icon
splash = "assets/splash.png"    # splash / launch image

[requirements]
packages = ["humanize", "httpx", "numpy"]
# extra_index_urls = ["https://wheels.example.com/simple"]

[plugins]
# paths = ["native/my_plugin"]  # project-local Swift/Kotlin plugins

[ios]
deployment_target = "13.0"
development_team = "ABCDE12345"
# bundle_id = "com.example.myapp"

[ios.signing]
export_method = "development"   # development | ad-hoc | app-store | enterprise
# provisioning_profile = "My App Distribution"

[android]
min_sdk = 24
target_sdk = 34
# abi_filters = ["arm64-v8a", "x86_64"]   # the default; add 32-bit ABIs if needed

[android.signing]
# keystore = "release.keystore"
# key_alias = "myapp"

Paths (icon, splash, keystore) are resolved relative to the project root. Invalid configuration fails fast with a specific, actionable error; run pn doctor to validate at any time.

Core identity, shared by both platforms.

!!! tip "Per-platform id overrides" By default both platforms use app.id. To diverge, set [android].application_id and/or [ios].bundle_id. The resolved value for either platform is available from pn app-id android / pn app-id ios.

Declare the device capabilities your app needs by name; PythonNative expands each into the right iOS Info.plist usage keys and Android <uses-permission> entries.

[permissions]
camera = "Scan receipts with your camera."   # string → iOS prompt text
notifications = true                          # true → sensible default
location_always = false                       # false → disabled

A value can be a string (used verbatim as the iOS permission-prompt text), true (use the capability's built-in default reason), or false (disable it without deleting the line). Unknown capability names are rejected at validation time.

See the dedicated Permissions guide for the full catalog and how each capability maps to native artifacts.

Asset generation requires Pillow, the pythonnative[build] optional dependency (pip install 'pythonnative[build]'). If Pillow isn't installed, the template's default assets are kept and the build still succeeds; pn doctor reports whether Pillow is available. See Building for release.

[requirements]
packages = ["humanize", "httpx>=0.27", "numpy"]
extra_index_urls = ["https://wheels.mycompany.example/simple"]

• iOS: the CLI resolves and installs one app_packages.<sdk> slice per SDK (device and Simulator); the Xcode run script bundles the matching one.
• Android: written into the staged template's requirements.txt (with the index options) and installed by Chaquopy into the APK at build time, once per ABI.

Run pn deps to see how each requirement resolves for every target before building. See PyPI packages for what works and why.

!!! warning "Don't list pythonnative" The CLI bundles the installed pythonnative package directly, so listing it here would install a second copy and confuse imports. Validation rejects it.

C-extension packages need wheels built for the target architectures (arm64-v8a/armeabi-v7a on Android; arm64/x86_64 for the iOS Simulator). Many popular extensions have no upstream mobile wheels yet.

[plugins]
paths = ["native/badge"]

Native plugins add Swift and Kotlin component managers and native modules to the app. Installed packages contribute theirs through the pythonnative.plugins entry point group automatically; paths is for native code that lives in the app repository itself. At build time each plugin's ios/*.swift is copied into PythonNativeKit and its android/**/*.kt into the pythonnative Gradle module, and the generated registration file calls every plugin's register. See Custom native components.

[ios]
deployment_target = "13.0"
development_team = "ABCDE12345"

[ios.signing]
export_method = "app-store"
provisioning_profile = "My App Distribution"

!!! note "Passwords stay out of the file" Only the env-var names live in pythonnative.toml; the passwords themselves are read from the environment at build time. See Building for release.

flowchart LR
    T["pythonnative.toml"] --> C["AppConfig (parsed + validated)"]
    C --> A["Android configurator<br/>package · gradle · manifest"]
    C --> I["iOS configurator<br/>Info.plist · xcodebuild · export"]
    C --> AS["Icon / splash generation"]
    A --> B["pn run / pn build"]
    I --> B
    AS --> B

Because parsing and validation happen once, up front, the platform configurators and builder always work from a fully-defaulted, valid config, so pn run and pn build behave consistently. For the build mechanics, continue to Building for release.