Skip to content

Python to APK on Windows

You can build an Android APK from a Python file on Windows itself: no WSL, no Linux virtual machine, no Google Colab notebook and no Android Studio. A few commands in PowerShell take you from an empty folder to an APK on your phone:

python -m pip install apkpy
apkpy setup
apkpy start hello
cd hello
apkpy run --usb

The rest of this page explains each step, what it installs on your computer and where, and what to do when a step stops.

Why this is usually hard on Windows

The best-known way to package Python for Android is Kivy's Buildozer, which drives python-for-android. Its installation guide says it plainly: Buildozer can be installed on Linux or macOS, Windows users must install WSL to use Linux. That is why so many tutorials send Windows users to WSL or to a Colab notebook first.

ApkPy builds on Windows directly because of how it works: it does not package a Python interpreter for the phone. It reads your Python file and writes an ordinary Android project (Java, layout XML, resources), and the Android build tools that compile that project, the JDK, Gradle and the Android SDK, all run on Windows.

Step 1: install ApkPy

You need Python 3.8 or newer from python.org. In PowerShell:

python -m pip install --upgrade apkpy

Step 2: check what the build needs

apkpy doctor

The doctor looks for three things and says what it found:

What Why Version
A JDK runs Gradle and compiles the generated Java 17 to 21
The Android SDK the Android platform the app is built against API 36
Gradle builds the APK from the generated project 8.7

If you already have Android Studio, its SDK is found and used. If java on your PATH is newer than 21, the doctor says so: Gradle 8.7 needs 17 to 21, and a newer Java is the most common reason a first build stops.

Step 3: let ApkPy install what is missing

apkpy setup

setup downloads only what the doctor did not find, into your user folder (C:\Users\<you>\.apkpy), so nothing is installed system-wide:

  • a Temurin JDK 17, into .apkpy\jdk;
  • Gradle 8.7, into .apkpy\gradle;
  • the Android SDK, through Google's sdkmanager, into .apkpy\sdk. This is the big download.

Run apkpy doctor again afterwards; it should end with READY.

Step 4: write the app

apkpy start hello
cd hello

The project has one file you edit, writehere.py. Replace it with:

from apkpy_lib import Screen, button, label, run, toast

home = Screen(id="home")
label("Built on Windows", id="title", screen=home)
button("Say hello", id="hello", command=lambda: toast("Hello from Python"), screen=home)

style = """
home {
    padding: 24px;
    gap: 16px;
}

title {
    font-size: 28px;
}
"""

if __name__ == "__main__":
    run(start_screen=home)

Before building anything, look at it on the desktop:

python writehere.py

That opens the Previewer, a window that shows the screens and runs the callbacks, so you can work on the interface without waiting for a build. It is not an emulator: the phone has the last word, and Previewer versus Android lists where the two can differ.

Step 5: build the APK

apkpy run

ApkPy writes the Android project under .apkpy\build, so your folder stays clean, runs Gradle, and copies the result next to you as hello-debug.apk. The first build is the slow one: Gradle downloads its own dependencies once.

Step 6: put it on the phone

Two ways, both optional:

apkpy run --usb
apkpy run --qr
  • --usb installs the APK on a phone connected by cable, with USB debugging turned on. It uses the adb that came with the SDK.
  • --qr serves the APK over your Wi-Fi and prints a QR code; scan it with the phone on the same network and allow the install when Android asks. (pip install qrcode makes the code scannable in the terminal.)

Or copy hello-debug.apk to the phone any way you like and open it.

When the app is ready to publish

apkpy release
apkpy release --aab

apkpy release builds a signed APK, and --aab builds the App Bundle that Google Play asks for. The key is created the first time and kept in .apkpy\keystores, so every later release is signed with the same one. Build and release covers the app's name, its identifier and its icon in apkpy.toml.

What ends up in the APK

The Python is translated when you build and is not on the phone, so there is no interpreter in the package. A small app is about 5 MB as a debug build and about 1.5 MB as a signed release shrunk with R8. The screens are Android's own views, and apkpy build gives you the generated project as a ZIP, to open in Android Studio if you ever want to read it.

The price of that design is said once here and in full on Compatibility and limits: packages from pip, such as requests or numpy, are not available on the phone, because there is no interpreter to import them. ApkPy has its own calls for network requests, storage, files and the device instead.

When a step stops

  • java is too new. Install a JDK 17 to 21, or let apkpy setup add its own; the doctor shows which one it will use.
  • failed to find target with hash string 'android-36'. The SDK is there without the platform the apps are built against. Troubleshooting has the fix.
  • USB: no device detected. Turn on USB debugging on the phone and accept the prompt that asks to allow USB debugging from this computer.
  • Python ApkPy cannot translate. The build stops at the line, with a code and the form to write instead. Friendly errors lists them.

Next: Installation in brief, the end-to-end tutorial, or how ApkPy compares with Kivy, BeeWare and Flet.