Quick search

Create a package for Android

You can create a package for android using the python-for-android project. This page explains how to download and use it directly on your own machine (see Packaging with python-for-android), use the prebuilt Kivy Android VM image, or use the Buildozer tool to automate the entire process. You can also see Packaging your application for the Kivy Launcher to run kivy programs without compiling them.

For new users, we recommend using Buildozer as the easiest way to make a full APK. You can also run your Kivy app without a compilation step with the Kivy Launcher app.

Kivy applications can be released on an Android market such as the Play store, with a few extra steps to create a fully signed APK.

The Kivy project includes tools for accessing Android APIs to accomplish vibration, sensor access, texting etc. These, along with information on debugging on the device, are documented at the main Android page.

NOTE: Currently, packages for Android can only be generated with Python 2.7. Python 3.3+ support is on the way...

Buildozer

Buildozer is a tool that automates the entire build process. It downloads and sets up all the prequisites for python-for-android, including the android SDK and NDK, then builds an apk that can be automatically pushed to the device.

Buildozer currently works only in Linux, and is an alpha release, but it already works well and can significantly simplify the apk build.

You can get buildozer at https://github.com/kivy/buildozer:

git clone https://github.com/kivy/buildozer.git
cd buildozer
sudo python2.7 setup.py install

This will install buildozer in your system. Afterwards, navigate to your project directory and run:

buildozer init

This creates a buildozer.spec file controlling your build configuration. You should edit it appropriately with your app name etc. You can set variables to control most or all of the parameters passed to python-for-android.

Finally, plug in your android device and run:

buildozer android debug deploy run

to build, push and automatically run the apk on your device.

Buildozer has many available options and tools to help you, the steps above are just the simplest way to build and run your APK. The full documentation is available here. You can also check the Buildozer README at https://github.com/kivy/buildozer.

Packaging with python-for-android

This section describes how to download and use python-for-android directly.

You’ll need:

  • A linux computer or a virtual machine
  • Java
  • Python 2.7 (not 2.6.)
  • Jinja2 (python module)
  • Apache ant
  • Android SDK

Setup Python for Android

First, install the prerequisites needed for the project:

Then open a console and type:

git clone git://github.com/kivy/python-for-android

Build your distribution

The distribution is a “directory” containing a specialized python compiled for Android, including only the modules you asked for. You can, from the same python-for-android, compile multiple distributions. For example:

  • One containing a minimal support without audio / video
  • Another containing audio, openssl etc.

To do that, you must use the script named distribute.sh:

./distribute.sh -m "kivy"

The result of the compilation will be saved into dist/default. Here are other examples of building distributions:

./distribute.sh -m "openssl kivy"
./distribute.sh -m "pil ffmpeg kivy"

Note

The order of modules provided are important, as a general rule put dependencies first and then the dependent modules, C libs come first then python modules.

To see the available options for distribute.sh, type:

./distribute.sh -h

Note

To use the latest Kivy development version to build your distribution, link “P4A_kivy_DIR” to the kivy folder environment variable to the kivy folder location. On linux you would use the export command, like this:

export P4A_kivy_DIR=/path/to/cloned/kivy/

Package your application

Inside the distribution (dist/default by default), you have a tool named build.py. This is the script that will create the APK for you:

./build.py --dir <path to your app>
           --name "<title>"
           --package <org.of.your.app>
           --version <human version>
           --icon <path to an icon to use>
           --orientation <landscape|portrait>
           --permission <android permission like VIBRATE> (multiple allowed)
           <debug|release> <installd|installr|...>

An example of using multiple permissions:

--permission INTERNET --permission WRITE_EXTERNAL_STORAGE

Full list of available permissions are documented here: http://developer.android.com/reference/android/Manifest.permission.html

For example, if we imagine that the touchtracer demo of Kivy is in the directory ~/kivy/examples/demo/touchtracer, you can do:

./build.py --dir ~/kivy/examples/demo/touchtracer \
    --package org.demo.touchtracer \
    --name "Kivy Touchtracer" --version 1.1.0 debug installd

You need to be aware that the default target Android SDK version for the build will be SDK v.8, which is the minimum required SDK version for kivy. You should either install this API version, or change the AndroidManifest.xml file (under dist/.../) to match your own target SDK requirements.

The debug binary will be generated in bin/KivyTouchtracer-1.1.0-debug.apk. The debug and installd parameters are commands from the Android project itself. They instruct build.py to compile the APK in debug mode and install on the first connected device.

You can then install the APK directly to your Android device as follows:

adb install -r bin/KivyTouchtracer-1.1.0-debug.apk

Packaging your application for the Kivy Launcher

The Kivy launcher is an Android application that runs any Kivy examples stored on your SD Card. To install the Kivy launcher, you must:

  1. Go to the Kivy Launcher page on the Google Play Store
  2. Click on Install
  3. Select your phone... And you’re done!

If you don’t have access to the Google Play Store on your phone/tablet, you can download and install the APK manually from http://kivy.org/#download.

Once the Kivy launcher is installed, you can put your Kivy applications in the Kivy directory in your external storage directory (often available at /sdcard even in devices where this memory is internal), e.g.:

/sdcard/kivy/<yourapplication>

<yourapplication> should be a directory containing:

# Your main application file:
main.py
# Some info Kivy requires about your app on android:
android.txt

The file android.txt must contain:

title=<Application Title>
author=<Your Name>
orientation=<portrait|landscape>

These options are just a very basic configuration. If you create your own APK using the tools above, you can choose many other settings.

Installation of Examples

Kivy comes with many examples, and these can be a great place to start trying the Kivy launcher. You can run them as below:

#. Download the `Kivy demos for Android <http://kivy.googlecode.com/files/kivydemo-for-android.zip>`_
#. Unzip the contents and go to the folder `kivydemo-for-android`
#. Copy all the the subfolders here to
/sdcard/kivy
  1. Run the launcher and select one of the Pictures, Showcase, Touchtracer, Cymunk or other demos...

Release on the market

If you have built your own APK with Buildozer or with python-for-android, you can create a release version that may be released on the Play store or other Android markets.

To do this, you must run Buildozer with the release parameter (e.g. buildozer android release), or if using python-for-android use the --release option to build.py. This creates a release APK in the bin directory, which you must properly sign and zipalign. The procedure for doing this is described in the Android documentation at http://developer.android.com/guide/publishing/app-signing.html - all the necessary tools come with the Android SDK.

Targeting Android

Kivy is designed to operate identically across platforms and as a result, makes some clear design decisions. It includes its own set of widgets and by default, builds an APK with all the required core dependencies and libraries.

It is possible to target specific Android features, both directly and in a (somewhat) cross-platform way. See the Using Android APIs section of the Kivy on Android documentation for more details.