Buildozer

1.5.0 · active · verified Fri Apr 17

Buildozer is a generic Python packager designed to create application bundles for various platforms, primarily Android and iOS, from Python projects (most notably Kivy applications). It automates the complex process of compiling Python code and its dependencies into native packages (APKs, AABs, IPAs). The current version is 1.5.0, and it generally follows Kivy's release cycle, with new versions typically released every few months to support updated SDKs and Kivy versions.

Common errors

```
Failed to find a python-for-android recipe for 'kivy' or 'python3'
```
cause Incorrect or missing requirements in `buildozer.spec`, or a very outdated `python-for-android` version that doesn't include the necessary recipes.

fix Open `buildozer.spec` and verify the `requirements` line (e.g., `requirements = python3,kivy`). Ensure `python-for-android` is updated or that a compatible version is installed.
```
Android SDK requires accepting licenses. To update and/or install new components and accept licenses run `sdkmanager --update`.
```
cause The Android SDK components are installed, but the necessary licenses haven't been accepted, preventing tools from being used.

fix Run `yes | sdkmanager --licenses` in your terminal to automatically accept all pending Android SDK licenses. Ensure `sdkmanager` is in your PATH.
```
Error: No such file or directory: '/path/to/android/sdk/tools/bin/sdkmanager'
```
cause The `ANDROID_HOME` environment variable is not set correctly, or the Android SDK Command-line Tools are not installed/located where Buildozer expects them.

fix Set the `ANDROID_HOME` environment variable to the root of your Android SDK installation. Install the latest Android SDK Command-line Tools using Android Studio or `sdkmanager` itself (if it's already partially set up).
```
Error: NameError: name 'raw_input' is not defined
```
cause This specific error indicates Buildozer is attempting to run with Python 2 syntax, while being executed in a Python 3 environment. This was a bug in older Buildozer versions.

fix Upgrade Buildozer to version 1.1.0 or newer. This issue was fixed in version 1.1.0.

Warnings

breaking Buildozer often requires specific versions of Android SDK/NDK components and `python-for-android`. Changes in Buildozer (e.g., v1.4.0 updating default NDK to 23b) or its dependencies can break existing build environments or require manual updates to `buildozer.spec` (e.g., `android.ndk`).
Fix: Review the changelog for required SDK/NDK versions or `buildozer.spec` changes. Ensure your SDK/NDK are updated via `sdkmanager` and `buildozer.spec` reflects the correct versions.
gotcha Building Android apps with Buildozer requires a fully configured development environment including Java Development Kit (JDK), Android SDK Command-line Tools, and Android NDK. Buildozer attempts to download these, but manual intervention for licenses or PATH setup is often needed, especially on new systems.
Fix: Ensure Java JDK (typically 11 or 17) is installed and `JAVA_HOME` is set. Install Android SDK Command-line Tools via Android Studio or `sdkmanager`. Accept all Android SDK licenses by running `sdkmanager --licenses`.
breaking Support for Android App Bundle (AAB) was introduced in Buildozer 1.3.0 and requires `python-for-android` v2022.03.13 or newer. Older versions of Buildozer or `python-for-android` will not be able to generate AABs.
Fix: Upgrade Buildozer to 1.3.0 or newer and ensure `python-for-android` is up-to-date. Configure `buildozer.spec` with `android.release_unit = aab`.
gotcha The default `python-for-android` toolchain target changed significantly around Buildozer v0.33. Older `buildozer.spec` files might have issues if they explicitly reference older toolchain names or configurations that are no longer standard.
Fix: If upgrading from very old Buildozer versions, it's often best to regenerate `buildozer.spec` with `buildozer init` and port over relevant settings, rather than manually updating an old one. Ensure your `buildozer.spec` doesn't use `android_old` unless specifically targeting legacy builds.

Install

pip install buildozer Install Buildozer

Quickstart

Buildozer is primarily a command-line tool. After installing Buildozer and creating a Kivy application (e.g., `main.py`), navigate to your project directory in the terminal. First, initialize Buildozer for your project, which creates a `buildozer.spec` file: ```bash buildozer init ``` Edit `buildozer.spec` to configure your app, paying attention to `requirements` (e.g., `requirements = python3,kivy`) and `android.min_sdk_version`. Then, build your application for Android (this will download SDKs/NDKs and compile): ```bash buildozer android debug ``` The resulting `.apk` or `.aab` will be found in the `bin/` directory.

# main.py
from kivy.app import App
from kivy.uix.label import Label

class MyApp(App):
    def build(self):
        return Label(text='Hello, Buildozer!')

if __name__ == '__main__':
    MyApp().run()

view raw JSON →