Welcome to Buildozer’s documentation!

Buildozer is a tool that aim to package mobiles application easily. It automates the entire build process, download the prerequisites like python-for-android, Android SDK, NDK, etc.

Buildozer manages a file named buildozer.spec in your application directory, describing your application requirements and settings such as title, icon, included modules etc. It will use the specification file to create a package for Android, iOS, and more.

Currently, Buildozer supports packaging for:

• Android: via Python for Android. You must have a Linux or OSX computer to be able to compile for Android.
• iOS: via Kivy iOS. You must have an OSX computer to be able to compile for iOS.
• Supporting others platform is in the roadmap (such as .exe for Windows, .dmg for OSX, etc.)

If you have any questions about Buildozer, please refer to the Kivy’s user mailing list.

Installation

Buildozer itself doesn’t depend on any library Python >= 3.3. Depending the platform you want to target, you might need more tools installed. Buildozer tries to give you hints or tries to install few things for you, but it doesn’t cover every situation.

First, install the buildozer project with:

pip3 install --user --upgrade buildozer

Targeting Android

Android on Ubuntu 20.04 (64bit)

(expected to work as well in later version, but only regularly tested in the latest LTS)

sudo apt update
sudo apt install -y git zip unzip openjdk-13-jdk python3-pip autoconf libtool pkg-config zlib1g-dev libncurses5-dev libncursesw5-dev libtinfo5 cmake libffi-dev libssl-dev
pip3 install --user --upgrade Cython==0.29.19 virtualenv  # the --user should be removed if you do this in a venv

# add the following line at the end of your ~/.bashrc file
export PATH=$PATH:~/.local/bin/

Android on Windows 10

To use buildozer in Windows 10 you need first to enable Windows Subsystem for Linux (WSL) and install a Linux distribution: https://docs.microsoft.com/en-us/windows/wsl/install-win10.

These instructions were tested with WSL 1 and Ubuntu 18.04 LTS.

After installing WSL and Ubuntu in your Windows 10 machine, open Ubuntu and do this:

1. Run the commands listed on the previous section (Android in Ubuntu 18.04 (64-bit).
2. Run the following commands:

# Use here the python version you need
sudo apt install -y python3.7-venv
# Create a folder for buildozer. For example: C:\buildozer
mkdir /mnt/c/buildozer
cd /mnt/c/buildozer
python3.7 -m venv venv-buildozer
source venv/bin/activate
python -m pip install --upgrade pip
python -m pip install --upgrade wheel
python -m pip install --upgrade cython
python -m pip install --upgrade virtualenv
python -m pip install --upgrade buildozer
# Restart your WSL terminal to enable the path change

Windows Subsystem for Linux does not have direct access to USB. Due to this, you need to install the Windows version of ADB (Android Debug Bridge):

• Go to https://developer.android.com/studio/releases/platform-tools and click on “Download SDK Platform-Tools for Windows”.
• Unzip the downloaded file to a new folder. For example, “C:\platform-tools”.

Before Using Buildozer

If you wish, clone your code to a new folder, where the build process will run.

You don’t need to create a virtualenv for your code requirements. But just add these requirements to a configuration file called buildozer.spec as you will see in the following sections.

Before running buildozer in your code folder, remember to go into the buildozer folder and activate the buildozer virtualenv.

Android on macOS

brew install openssl
sudo ln -sfn /usr/local/opt/openssl /usr/local/ssl
brew install pkg-config autoconf automake
python3 -m pip install --user --upgrade Cython==0.29.19 virtualenv  # the --user should be removed if you do this in a venv

# add the following line at the end of your `~/.bashrc` file
export PATH=$PATH:~/Library/Python/3.7/bin

TroubleShooting

Buildozer stuck on “Installing/updating SDK platform tools if necessary”

Press “y” then enter to continue, the license acceptance system is silently waiting for your input

Aidl not found, please install it.

Buildozer didn’t install a necessary package

~/.buildozer/android/platform/android-sdk/tools/bin/sdkmanager "build-tools;29.0.0"

Then press “y” then enter to accept the license.

python-for-android related errors

See the dedicated p4a troubleshooting documentation.

Targeting IOS

Install XCode and command line tools (through the AppStore)

Install homebrew (https://brew.sh)

brew install pkg-config sdl2 sdl2_image sdl2_ttf sdl2_mixer gstreamer autoconf automake

Install pip and virtualenv

python3 -m pip install --user --upgrade pip virtualenv kivy-ios

Quickstart

Let’s get started with Buildozer!

Init and build for Android

1. Buildozer will try to guess the version of your application, by searching a line like __version__ = “1.0.3” in your main.py. Ensure you have one at the start of your application. It is not mandatory but heavily advised.

2. Create a buildozer.spec file, with:

   buildozer init
   

3. Edit the buildozer.spec according to the specifications. You should at least change the title, package.name and package.domain in the [app] section.

4. Start a Android/debug build with:

   buildozer -v android debug
   

5. Now it’s time for a coffee / tea, or a dinner if you have a slow computer. The first build will be slow, as it will download the Android SDK, NDK, and others tools needed for the compilation. Don’t worry, thoses files will be saved in a global directory and will be shared across the different project you’ll manage with Buildozer.

6. At the end, you should have an APK or AAB file in the bin/ directory.

Run my application

Buildozer is able to deploy the application on your mobile, run it, and even get back the log into the console. It will work only if you already compiled your application at least once:

buildozer android deploy run logcat

For iOS, it would look the same:

buildozer ios deploy run

You can combine the compilation with the deployment:

buildozer -v android debug deploy run logcat

You can also set this line at the default command to do if Buildozer is started without any arguments:

buildozer setdefault android debug deploy run logcat

# now just type buildozer, and it will do the default command
buildozer

To save the logcat output into a file named my_log.txt (the file will appear in your current directory):

buildozer -v android debug deploy run logcat > my_log.txt

To see your running application’s print() messages and python’s error messages, use:

buildozer -v android deploy run logcat | grep python

Run my application from Windows 10

• Plug your Android device on a USB port.
• Open Windows PowerShell, go into the folder where you installed the Windows version of ADB, and activate the ADB daemon. When the daemon is started you must see a number besides the word “device” meaning your device was correctly detected. In case of trouble, try another USB port or USB cable.

cd C:\platform-tools\
.\adb.exe devices

• Open the Linux distribution you installed on Windows Subsystem for Linux (WSL) and proceed with the deploy commands:

buildozer -v android deploy run

It is important to notice that Windows ADB and Buildozer installed ADB must be the same version. To check the versions, open PowerShell and type:

cd C:\platform-tools\
.\adb.exe version
wsl
cd ~/.buildozer/android/platform/android-sdk/platform-tools/
./adb version

Install on non-connected devices

If you have compiled a package, and want to share it easily with others devices, you might be interested with the serve command. It will serve the bin/ directory over HTTP. Then you just have to access to the URL showed in the console from your mobile:

buildozer serve

Specifications

This document explains in detail all the configuration tokens you can use in buildozer.spec.

Section [app]

• title: String, title of your application.

  It might be possible that some characters are not working depending on the targeted platform. It’s best to try and see if everything works as expected. Try to avoid too long titles, as they will also not fit in the title displayed under the icon.

• package.name: String, package name.

  The Package name is one word with only ASCII characters and/or numbers. It should not contain any special characters. For example, if your application is named Flat Jewels, the package name can be flatjewels.

• package.domain: String, package domain.

  Package domain is a string that references the company or individual that did the app. Both domain+name will become your application identifier for Android and iOS, choose it carefully. As an example, when the Kivy`s team is publishing an application, the domain starts with org.kivy.

• source.dir: String, location of your application sources.

  The location must be a directory that contains a main.py file. It defaults to the directory where buildozer.spec is.

• source.include_exts: List, file extensions to include.

  By default, not all files in your source.dir are included, but only some of them (py,png,jpg,kv,atlas), depending on the extension. Feel free to add your own extensions, or use an empty value if you want to include everything.

• source.exclude_exts: List, file extensions to exclude.

  In contrary to source.include_exts, you could include all the files you want except the ones that end with an extension listed in this token. If empty, no files will be excluded based on their extensions.

• source.exclude_dirs: List, directories to exclude.

  Same as source.exclude_exts, but for directories. You can exclude your tests and bin directory with:

  source.exclude_dirs = tests, bin
  

• source.exclude_patterns: List, files to exclude if they match a pattern.

  If you have a more complex application layout, you might need a pattern to exclude files. It also works if you don’t have a pattern. For example:

  source.exclude_patterns = license,images/originals/*
  

• version.regex: Regex, Regular expression to capture the version in version.filename.

  The default capture method of your application version is by grepping a line like this:

  __version__ = "1.0"
  

  The 1.0 will be used as a version.

• version.filename: String, defaults to the main.py.

  File to use for capturing the version with version.regex.

• version: String, manual application version.

  If you don’t want to capture the version, comment out both version.regex and version.filename, then put the version you want directly in the version token:

  # version.regex =
  # version.filename =
  version = 1.0
  

• requirements: List, Python modules or extensions that your application requires.

  The requirements can be either a name of a recipe in the Python-for-android project, or a pure-Python package. For example, if your application requires Kivy and requests, you need to write:

  requirements = kivy,requests
  

  If your application tries to install a Python extension (ie, a Python package that requires compilation), and the extension doesn’t have a recipe associated to Python-for-android, it will not work. We explicitly disable the compilation here. If you want to make it work, contribute to the Python-for-android project by creating a recipe. See Contribute.

• presplash.filename: String, loading screen of your application.

  Presplash is the image shown on the device during application loading. It is called presplash on Android, and Loading image on iOS. The image might have different requirements depending the platform. Currently, Buildozer works well only with Android, iOS support is not great on this.

  The image must be a JPG or PNG, preferable with Power-of-two size, e.g., a 512x512 image is perfect to target all the devices. The image is not fitted, scaled, or anything on the device. If you provide a too-large image, it might not fit on small screens.

• icon.filename: String, icon of your application.

  The icon of your application. It must be a PNG of 512x512 size to be able to cover all the various platform requirements.

• orientation: String, orientation of the application.

  Indicate the orientation that your application supports. Defaults to landscape, but can be changed to portrait or all.

• fullscreen: Boolean, fullscreen mode.

  Defaults to true, your application will run in fullscreen. Means the status bar will be hidden. If you want to let the user access the status bar, hour, notifications, use 0 as a value.

Contribute

Write your own recipe

A recipe allows you to compile libraries / python extension for the mobile. Most of the time, the default compilation instructions doesn’t work for the target, as ARM compiler / Android NDK introduce specificities that the library you want doesn’t handle correctly, and you’ll need to patch. Also, because the Android platform cannot load more than 64 inline dynamic libraries, we have a mechanism to bundle all of them in one to ensure you’ll not hit this limitation.

To test your own recipe via Buildozer, you need to:

1. Fork Python for Android, and clone your own version (this will allow easy contribution later):

   git clone https://github.com/YOURNAME/python-for-android
   

2. Change your buildozer.spec to reference your version:

   p4a.source_dir = /path/to/your/python-for-android
   

3. Copy your recipe into python-for-android/recipes/YOURLIB/recipe.sh

4. Rebuild.

When you correctly get the compilation and your recipe works, you can ask us to include it in the python-for-android project, by issuing a Pull Request:

1. Create a branch:

   git checkout --track -b recipe-YOURLIB origin/master
   

2. Add and commit:

   git add python-for-android/recipes/YOURLIB/*
   git commit -am 'Add support for YOURLIB`
   

3. Push to Github

   git push origin master

4. Go to https://github.com/YOURNAME/python-for-android, and you should see your new branch and a button “Pull Request” on it. Use it, write a description about what you did, and Send!

Indices and tables

• Index
• Module Index
• Search Page