Skip to content

Quickstart: build an Android app

In this quickstart you build a minimal Kivy app as a debug APK (Android application package) and run it on an emulator or a device. You can do this from Windows, macOS, or Linux. Android does not require a Mac.

Before you begin

  • kivyforge, installed as described in Install kivyforge.
  • A JDK (Java Development Kit) in the range listed in Supported versions, in JAVA_HOME or on your PATH. It must be a full JDK: a JRE has no javac, and kivyforge doctor -p android fails it. Android Studio's bundled JDK may be newer than that range; kivyforge doctor -p android tells you. If it is, install a separate one, such as Eclipse Temurin.
  • The Android SDK with command-line tools, build-tools, platform-tools, and the Android NDK. Android Studio installs the SDK. Add the NDK and command-line tools from its SDK Manager, then accept the SDK licenses (see SDK licenses and sdkmanager).
  • Somewhere to run the app: a physical device with USB debugging turned on, or an AVD (Android Virtual Device, an emulator image) created in Android Studio's Device Manager.
  • git, to fetch the example app.

SDK licenses and sdkmanager

Gradle installs missing SDK packages during a build (CMake, for one), but only once the SDK license is recorded under <sdk>/licenses/.

  • Older command-line tools record it when you run sdkmanager --licenses and accept.
  • Command-line tools 23 and later replace sdkmanager with a wrapper around Google's Android CLI. There, sdkmanager --licenses prints "no longer needed" and does nothing; installing any package, such as sdkmanager platform-tools, records the license without asking.

Two more differences with the new wrapper. An install that fails, such as a mistyped package name, prints "not found" but still exits with status 0, so check the result with sdkmanager --list_installed. And the Android CLI collects usage data unless you run it with --no-metrics, which the sdkmanager wrapper does not pass; the android binary next to it in cmdline-tools/latest/bin accepts the flag (android --no-metrics sdk install <package>).

Step 1: Get the example app

git clone https://github.com/ElliotGarbus/kivyforge.git
cd kivyforge/examples/mobile/hello-android

This example ships a committed pylock.android.toml, so you can build without running kivyforge lock. Do not edit pyproject.toml during this quickstart: any edit makes the lockfile out of date, and the build then asks you to re-lock.

Step 2: Check your environment

kivyforge doctor -p android

doctor checks the JDK, the SDK and its licenses, build-tools, the NDK, the emulator, and adb (Android Debug Bridge). Fix any FAIL before you continue. It prints the sdkmanager command for anything that is missing.

Step 3: Build the debug APK

kivyforge build -p android --debug --abi ABI

Replace ABI with the ABI (application binary interface) of the device you plan to run on:

  • x86_64 for an emulator on an Intel or AMD computer.
  • arm64_v8a for a physical device, or for an emulator on an Apple Silicon Mac.

kivyforge generates a Gradle project in hello-android-android/, stages the Python runtime and wheels, and drives Gradle to produce hello-android-android/app/build/outputs/apk/debug/app-debug.apk. The first build downloads Gradle and its dependencies, so it takes several minutes.

Step 4: Run it

kivyforge run -p android

run picks a target: a single connected physical device, else a running emulator, else it boots your first AVD. It then rebuilds the debug APK for that target's ABI, installs it, launches it, and prints the app's log lines. The app opens full screen and shows Hello from kivyforge.

Contract smoke test

kivyforge run -p android --smoke runs an instrumented test that kivyforge generates, instead of launching the app. It checks the Python runtime, the extension-module loader, and the pyjnius bridge on the device. CI runs it as kivyforge run --smoke --release -p android.

Verify

The launcher on the device shows the app as Hello Android, the display_name from pyproject.toml. To see what a build produced as structured data, run:

kivyforge build -p android --debug --abi ABI --json

Replace ABI as in Step 3. The data.artifacts array names the generated project and the .apk, with paths relative to the project root.

What's next