Android Guide¶

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

What gets generated¶

pn run android unpacks the bundled Android template (Kotlin + Chaquopy) into build/android/android_template and copies your app/ into the template's app/src/main/python/app/.

No network is required for the template itself; the template zip is bundled with the package.

Component model¶

Your app/ directory contains @pn.component function components. The native Android template uses create_page() internally to bootstrap your root component inside a PageFragment. You don't call create_page() directly — just export your component and configure the entry point in pythonnative.json.

Run¶

pn run android

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.

Viewing logs¶

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:

Tag	Source
`python.stdout`	`print()` / anything written to `sys.stdout`
`python.stderr`	tracebacks / anything written to `sys.stderr`
`MainActivity`, `PageFragment`, `Navigator`	Kotlin template lifecycle
`AndroidRuntime:E`	Fatal Java/Kotlin exceptions

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).

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

Clean¶

Remove the build directory safely:

pn clean

Troubleshooting¶

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.