Skip to content

Setting up buildozer for kivy

Setting Up Buildozer for Kivy 2.3.0 with Docker: A Guide for New Users

In my free time, I explored using Kivy to create mobile applications. However, the current state of Kivy's tooling, specifically Buildozer, presents significant challenges for beginners. Buildozer relies on legacy dependencies and specific tools, which makes it incompatible with modern systems like Ubuntu 24.04 (as of December 2024). This guide aims to resolve that challenge by leveraging Docker to streamline the Buildozer setup process. We’ll use a modern Docker image containing a pre-configured version of Buildozer and walk through the steps to compile your Kivy app into an Android .apk file.

Step 1: Install Docker

Before starting, you need Docker installed on your system. Follow the official Docker installation guide based on your operating system: - Docker for Windows - Docker for Linux

Verify the installation by running: 

docker --version
You should see the installed version of Docker displayed.

Step 2: Pull the Base Buildozer Docker Image

We will use a community-maintained Docker image optimized for Kivy and Buildozer: 

docker pull qiruizheng/buildozer
This command downloads the Docker image qiruizheng/buildozer to your system. It contains a working Buildozer setup compatible with Kivy 2.3.0.

Step 3: Prepare the Workspace Directory

To compile your Kivy application, you need a shared folder between your host system and the Docker container. For Windows users: 1. Ensure that the directory C:\kivy exists. 2. You can create it manually or by running the following command in a Windows terminal: 

mkdir C:\kivy
For Linux users, use a similar approach to create a directory such as ~/kivy.

Step 4: Run the Docker Container

The following command starts the Docker container and mounts the C:\kivy directory (or equivalent on Linux) to /mnt inside the container: 

docker run -d -v C:/kivy:/mnt --user root qiruizheng/buildozer tail -f /dev/null

Explanation:

  • -d runs the container in detached mode (background).
  • -v C:/kivy:/mnt mounts the host folder C:\kivy to /mnt in the container for file sharing.
  • --user root ensures we have administrative privileges inside the container.
  • qiruizheng/buildozer is the name of the base Docker image.
  • tail -f /dev/null keeps the container running indefinitely.

To confirm that the container is running, list all active containers: 

docker ps
Take note of the Container ID for the next steps.

Step 5: Access the Running Docker Container

We now need to interact with the container to configure and use Buildozer. First, identify the running container's ID: 

docker ps -a
Once you have the Container ID, access the container's shell using: 
docker exec -it <container_id> sh
Replace <container_id> with the actual ID of your running container.

Changing User Passwords

Inside the container, change the root and Kivy user passwords as a precaution: 

passwd root
passwd kivy
You’ll be prompted to enter new passwords for both users.

Step 6: Understanding the Kivy Project Structure

Inside the container, you’ll find a sample Kivy project in the home directory named myapp. The folder structure looks like this: 

myapp/
|-- buildozer.spec    # Configuration file for Buildozer
|-- bin/              # Compiled .apk files will appear here
|-- main.py           # Your Kivy application's entry point
- buildozer.spec: This file contains all settings for packaging the Kivy app (e.g., app name, version, and dependencies). - bin/: Buildozer will output the compiled .apk file here. - main.py: This is your main application code.

Note: This guide focuses on setting up Buildozer, not on understanding Kivy's programming fundamentals.

Step 7: Compile the Kivy App into an APK File

Run the following command to clean up any previous builds, compile the app, and copy the .apk file to the shared directory: 

rm -rf /mnt/* && buildozer android debug && cp ./bin/* /mnt

Explanation:

  • rm -rf /mnt/* ensures the shared folder is clean before the build.
  • buildozer android debug triggers the build process to create a debug version of your app.
  • cp ./bin/* /mnt copies the compiled .apk file into the shared C:\kivy folder.

Step 8: Install the APK on Your Android Phone

In a new termainl, we can install the generated .apk file onto your phone, use ADB (Android Debug Bridge). If you don’t have ADB installed on Windows, install it using Chocolatey: 

choco install adb
For Linux users, install ADB using your package manager: 
sudo apt install adb
Navigate to the shared folder C:\kivy (or your Linux equivalent) and run the following command to install the app: 
adb install <name_of_apk_file>
Replace <name_of_apk_file> with the actual name of the .apk file. Ensure your Android device is connected via USB and has Developer Mode and USB Debugging enabled.

Within moments, the app will be installed and ready to launch on your phone.

Conclusion

By using Docker and the qiruizheng/buildozer image, we have bypassed the challenges of setting up Buildozer on modern systems like Ubuntu 24.04. This approach ensures that Kivy 2.3.0 works seamlessly, allowing you to focus on building and compiling your app without dependency issues. Happy coding!