Basic steps to build and run an Android project generated by pn.

pn run android unpacks the bundled Android template into build/android/android_template and copies your app/ into the template's app/src/main/python/app/. The template is two Gradle modules: app/ (the thin Kotlin host: MainActivity, Chaquopy setup, the PythonHost callback) and pythonnative/ (the native rendering core: component managers, gesture recognizers, animations, and native modules, with no Chaquopy dependency). Native plugins from [plugins].paths and installed packages are copied into the pythonnative/ module before Gradle runs.

No network is required for the template itself; the template zip is bundled with the package. [requirements].packages are written to the staged project's requirements.txt and installed by Chaquopy during the Gradle build, once per ABI in [android].abi_filters, from PyPI, Chaquopy's own wheel index, and any [requirements].extra_index_urls. Run pn deps android first to preview what will resolve; see PyPI packages.

• Android 7.0 (API 24) or newer, the Chaquopy 17 floor; [android].min_sdk can't go lower.
• 64-bit ABIs only (arm64-v8a, x86_64): CPython 3.13+ on Chaquopy and PEP 738 wheels don't ship 32-bit builds.
• JDK 17 and the Android SDK; pn doctor android checks both.
• Android NDK and CMake 3.22.1 for the bundled Yoga C++ library. Gradle builds it for each configured ABI. Install these SDK components through Android Studio's SDK Manager if they're missing.

Your app/ directory contains @pn.component function components. The native Android template boots Python with pythonnative.bootstrap.start() and asks the Host native module to mount your root component inside a ScreenFragment (a thin subclass of the runtime's PNScreenFragment). You don't call anything for this; just export your component and configure the entry point in pythonnative.toml (app.entry_point).

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:

pn run android --prepare-only

This will stage files under build/android/android_template so you can open it in Android Studio if you prefer.

After the app is installed and launched, pn run android tails adb logcat and streams it back to your terminal. The filter is scoped to the tags Chaquopy and the template use, so you get Python output without the usual logcat noise:

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.

Remove the build directory safely:

pn clean

• If gradlew fails due to JDK path on macOS, ensure JAVA_HOME is set (the CLI attempts to detect Homebrew openjdk@17).
• Ensure an Android emulator or device is available for installDebug.

See Troubleshooting for the most common errors and their fixes.

• Try the iOS counterpart: iOS guide.
• Build a real screen: Examples.
• Iterate faster with Hot reload.