Getting up and running on python-for-android (p4a) is a simple process and should only take you a couple of minutes. We’ll refer to Python for android as p4a in this documentation.
- requirements: For p4a, your applications dependencies are requirements similar to the standard requirements.txt, but with one difference: p4a will search for a recipe first instead of installing requirements with pip.
- recipe: A recipe is a file that defines how to compile a requirement. Any libraries that have a Python extension must have a recipe in p4a, or compilation will fail. If there is no recipe for a requirement, it will be downloaded using pip.
- build: A build refers to a compiled recipe.
- distribution: A distribution is the final “build” of all your compiled requirements, as an Android project that can be turned directly into an APK. p4a can contain multiple distributions with different sets of requirements.
- bootstrap: A bootstrap is the app backend that will start your application. Your application could use SDL2 as a base, or a web backend like Flask with a WebView bootstrap. Different bootstraps can have different build options.
p4a is now available on Pypi, so you can install it using pip:
pip install python-for-android
You can also test the master branch from Github using:
pip install git+https://github.com/kivy/python-for-android.git
p4a has several dependencies that must be installed:
- cython (can be installed via pip)
- a Java JDK (e.g. openjdk-8)
- zlib (including 32 bit)
- libncurses (including 32 bit)
- virtualenv (can be installed via pip)
- ccache (optional)
- autoconf (for ffpyplayer_codecs recipe)
- libtool (for ffpyplayer_codecs recipe)
- cmake (required for some native code recipes like jpeg’s recipe)
On recent versions of Ubuntu and its derivatives you may be able to install most of these with:
sudo dpkg --add-architecture i386 sudo apt-get update sudo apt-get install -y build-essential ccache git zlib1g-dev python2.7 python2.7-dev libncurses5:i386 libstdc++6:i386 zlib1g:i386 openjdk-8-jdk unzip ant ccache autoconf libtool
On Arch Linux (64 bit) you should be able to run the following to
install most of the dependencies (note: this list may not be
complete). gcc-multilib will conflict with (and replace) gcc if not
already installed. If your installation is already 32-bit, install the
same packages but without
sudo pacman -S jdk7-openjdk python2 python2-pip python2-kivy mesa-libgl lib32-mesa-libgl lib32-sdl2 lib32-sdl2_image lib32-sdl2_mixer sdl2_ttf unzip gcc-multilib gcc-libs-multilib
Installing Android SDK¶
You need to download and unpack the Android SDK and NDK to a directory (let’s say $HOME/Documents/):
For the Android SDK, you can download ‘just the command line
tools’. When you have extracted these you’ll see only a directory
tools, and you will need to run extra commands to install
the SDK packages needed.
For Android NDK, note that modern releases will only work on a 64-bit operating system. The minimal, and recommended, NDK version to use is r17c:
- Go to ndk downloads page
- Windows users should create a virtual machine with an GNU Linux os installed, and then you can follow the described instructions from within your virtual machine.
If you are using a 32-bit distribution (or hardware), the latest usable NDK version is r10e, which can be downloaded here:
Since the python2 recipe updated to version 2.7.15, the build system has been changed and you should use an old release of python-for-android, which contains the legacy python recipe (v2.7.2). The last python-for-android release with the legacy version of python is version 0.6.0.
First, install an API platform to target. You can replace
a different platform number, but keep in mind other API versions
are less well-tested, and older devices are still supported
(down to the specified minimum API/NDK API level):
Second, install the build-tools. You can use
$SDK_DIR/tools/bin/sdkmanager --list to see all the
possibilities, but 26.0.2 is the latest version at the time of writing:
Then, you can edit your
~/.bashrc or other favorite shell to include new environment variables necessary for building on android:
# Adjust the paths! export ANDROIDSDK="$HOME/Documents/android-sdk-27" export ANDROIDNDK="$HOME/Documents/android-ndk-r17c" export ANDROIDAPI="26" # Target API version of your application export NDKAPI="19" # Minimum supported API version of your application export ANDROIDNDKVER="r10e" # Version of the NDK you installed
You have the possibility to configure on any command the PATH to the SDK, NDK and Android API using:
--sdk-dir PATHas an equivalent of $ANDROIDSDK
--ndk-dir PATHas an equivalent of $ANDROIDNDK
--android-api VERSIONas an equivalent of $ANDROIDAPI
--ndk-api VERSIONas an equivalent of $NDKAPI
--ndk-version VERSIONas an equivalent of $ANDROIDNDKVER
Build a Kivy or SDL2 application¶
To build your application, you need to specify name, version, a package identifier, the bootstrap you want to use (sdl2 for kivy or sdl2 apps) and the requirements:
p4a apk --private $HOME/code/myapp --package=org.example.myapp --name "My application" --version 0.1 --bootstrap=sdl2 --requirements=python3,kivy
Note on `–requirements`: you must add all libraries/dependencies your app needs to run. Example: –requirements=python3,kivy,vispy. For an SDL2 app, kivy is not needed, but you need to add any wrappers you might use (e.g. pysdl2).
This p4a apk … command builds a distribution with python3, kivy, and everything else you specified in the requirements. It will be packaged using a SDL2 bootstrap, and produce an .apk file.
- While python2 is still supported by python-for-android, it will possibly no longer receive patches by the python creators themselves in 2020. Migration to Python 3 is recommended!
- You can also use
--bootstrap=pygame, but this bootstrap is deprecated and not well-tested.
Build a WebView application¶
To build your application, you need to have a name, version, a package identifier, and explicitly use the webview bootstrap, as well as the requirements:
p4a apk --private $HOME/code/myapp --package=org.example.myapp --name "My WebView Application" --version 0.1 --bootstrap=webview --requirements=flask --port=5000
Please note as with kivy/SDL2, you need to specify all your additional requirements/depenencies.
You can also replace flask with another web framework.
--port=5000 with the port on which your app will serve a
website. The default for Flask is 5000.
You can pass other command line arguments to control app behaviours such as orientation, wakelock and app permissions. See Bootstrap options.
If anything goes wrong and you want to clean the downloads and builds to retry everything, run:
If you just want to clean the builds to avoid redownloading dependencies, run:
p4a clean_builds && p4a clean_dists
You can see the list of the available recipes with:
If you are contributing to p4a and want to test a recipes again, you need to clean the build and rebuild your distribution:
p4a clean_recipe_build RECIPENAME p4a clean_dists # then rebuild your distribution
You can write “private” recipes for your application, just create a
p4a-recipes folder in your build directory, and place a recipe in
it (edit the
mkdir -p p4a-recipes/myrecipe touch p4a-recipes/myrecipe/__init__.py
Every time you start a new project, python-for-android will internally create a new distribution (an Android build project including Python and your other dependencies compiled for Android), according to the requirements you added on the command line. You can force the reuse of an existing distribution by adding:
p4a apk --dist_name=myproject ...
This will ensure your distribution will always be built in the same directory, and avoids using more disk space every time you adjust a requirement.
You can list the available distributions:
And clean all of them:
python-for-android checks in the current directory for a configuration
.p4a. If found, it adds all the lines as options to the
command line. For example, you can add the options you would always
include such as:
--dist_name my_example --android_api 27 --requirements kivy,openssl
Overriding recipes sources¶
You can override the source of any recipe using the
$P4A_recipename_DIR environment variable. For instance, to test
your own Kivy branch you might set:
The specified directory will be copied into python-for-android instead of downloading from the normal url specified in the recipe.
setup.py file (experimental)¶
If your application is also packaged for desktop using setup.py,
you may want to use your setup.py instead of the
--requirements option to avoid specifying things twice.
For that purpose, check out distutils/setuptools integration