Gradle plugin#

Chaquopy is distributed as a plugin for Android’s Gradle-based build system. It can be used in any app which meets the following requirements:

  • In your project’s top-level build.gradle file, the Android Gradle plugin version should be between 4.1 and 7.2. Older versions as far back as 2.2 are supported by older versions of Chaquopy.

    • The Android plugin may be listed as com.android.application, com.android.library or com.android.tools.build:gradle.

Basic setup#

Gradle plugin#

In your project’s settings.gradle or build.gradle file, find the repositories list in pluginManagement or buildscript, and make sure it includes mavenCentral(). If your project was generated by a recent version of Android Studio, this line should already be there.

Note

The following instructions use the plugins syntax. If your project uses the previous buildscript and apply syntax, follow the instructions here, but replace the Chaquopy version number with the current one shown below.

In your top-level build.gradle file, set the Chaquopy version:

plugins {
    id 'com.chaquo.python' version '13.0.0' apply false
}

In the module-level build.gradle file (usually in the app directory), apply the Chaquopy plugin after the Android plugin:

plugins {
    id 'com.android.application'
    id 'com.chaquo.python'
}

All other configuration will be done in this module-level build.gradle. The examples below will show the configuration within defaultConfig, but it can also be done within a product flavor.

The Chaquopy plugin can also be used in an Android library module (AAR). However, it can only be used in one module in a project: either in the app module, or in exactly one library module. If you use it in multiple modules, the build may fail, and even if it succeeds, only one module’s Python code will be included in the app

ABI selection#

The Python interpreter is a native component, so you must use the abiFilters setting to specify which ABIs you want the app to support. The currently available ABIs are:

  • armeabi-v7a, supported by virtually all Android devices.

  • arm64-v8a, supported by most recent Android devices.

  • x86, for the Android emulator.

  • x86_64, for the Android emulator.

During development you’ll probably want to enable them all, i.e.:

defaultConfig {
    ndk {
       abiFilters "armeabi-v7a", "arm64-v8a", "x86", "x86_64"
    }
}

There’s no need to actually install the NDK, as all of Chaquopy’s native libraries are already pre-compiled and stripped.

Each ABI will add several MB to the size of the app, plus the size of any native requirements. If you find this makes your app too large, see the FAQ.

Python version#

You can set your app’s Python version like this:

defaultConfig {
    python {
        version "3.8"
    }
}

In this version of Chaquopy, the default Python version is 3.8, and the other available versions are 3.9, 3.10 and 3.11. Note that versions other than the default may have fewer packages available.

buildPython#

Some features require Python 3.5 or later to be available on the build machine. These features are indicated by a note in their documentation sections.

By default, Chaquopy will try to find Python on the PATH with the standard command for your operating system, first with a matching minor version, and then with a matching major version. For example, if your app’s Python version is 3.8, then:

  • On Linux and Mac it will try python3.8, then python3.

  • On Windows, it will try py -3.8, then py -3.

If this doesn’t work for you, set your Python command using the buildPython setting. For example, on Windows you might use one of the following:

defaultConfig {
    python {
        buildPython "C:/path/to/python.exe"
        buildPython "C:/path/to/py.exe", "-3.8"
    }
}

Development#

Source code#

By default, Chaquopy will look for Python source code in the python subdirectory of each source set. For example, the Python code for the main source set should go in src/main/python.

To include Python source code from other directories, use the android.sourceSets block. For example:

android {
    sourceSets {
        main {
            python.srcDir "some/other/dir"
        }
    }
}

Note

The setRoot method only takes effect on the standard Android directories. If you want to set the Python directory as well, you must do so explicitly, e.g.:

main {
    setRoot "some/other/main"
    python.srcDirs = ["some/other/main/python"]
}

As with Java, it is usually an error if the source directories for a given build variant include multiple copies of the same filename. This is only permitted if the duplicate files are all empty, such as may happen with __init__.py.

Startup#

It’s important to structure the app so that Python.start() is always called with an AndroidPlatform before attempting to run Python code. There are two basic ways to achieve this:

If the app always uses Python, then call Python.start() from a location which is guaranteed to run exactly once per process, such as Application.onCreate(). The easiest way to do this is to use PyApplication, or your own subclass of it. Simply add the following attribute to the <application> element in AndroidManifest.xml:

android:name="com.chaquo.python.android.PyApplication"

Alternatively, if the app only sometimes uses Python, then call Python.start() after first checking whether it’s already been started:

// "context" must be an Activity, Service or Application object from your app.
if (! Python.isStarted()) {
    Python.start(new AndroidPlatform(context));
}

Requirements#

Note

This feature requires Python on the build machine, which can be configured with the buildPython setting.

External Python packages may be built into the app using the pip block in build.gradle. Within this block, add install lines, which can take any of the forms accepted by pip install. For example:

defaultConfig {
    python {
        pip {
            // A requirement specifier, with or without a version number:
            install "scipy"
            install "requests==2.24.0"

            // An sdist or wheel filename, relative to the project directory:
            install "MyPackage-1.2.3-py2.py3-none-any.whl"

            // A directory containing a setup.py, relative to the project
            // directory (must contain at least one slash):
            install "./MyPackage"

            // "-r"` followed by a requirements filename, relative to the
            // project directory:
            install "-r", "requirements.txt"
        }
    }
}

In our most recent tests, Chaquopy could install over 90% of the top 1000 packages on PyPI. This includes almost all pure-Python packages, plus a constantly-growing selection of packages with native components. To see which native packages are currently available, you can browse the repository here. To request a package to be added or updated, or for any other problem with installing requirements, please visit our issue tracker.

To pass options to pip install, give them as a comma-separated list to the options setting. For example:

pip {
    options "--extra-index-url", "https://example.com/private/repository"
    install "MyPackage==1.2.3"
}

Any options in the pip documentation may be used, except for those which relate to the target environment, such as --target, --user or -e. If there are multiple options lines, they will be combined in the order given.

Static proxy generator#

Note

This feature requires Python on the build machine, which can be configured with the buildPython setting.

The static proxy feature allows a Python class to extend a Java class, or to be referenced directly in Java code or the AndroidManifest.xml file without going through the Java API.

To use this feature, write your Python classes using the syntax described in the “Static proxy” section, then list their containing modules in the build.gradle file as follows:

defaultConfig {
    python {
        staticProxy "module.one", "module.two"
    }
}

Packaging#

Data files#

Any data files in your source code and requirements will be automatically built into your app. You can read them at runtime using a path relative to __file__.

For example, if the data file is in the same directory as the Python file:

from os.path import dirname, join
filename = join(dirname(__file__), "filename.txt")

You can then pass this filename to open, or any other function which reads a file.

If the data file and the Python file are in different directories, then change the path accordingly. For example, if the Python file is alpha/hello.py, and the data file is bravo/filename.txt, then replace filename.txt above with ../bravo/filename.txt.

Data files within a top-level package (i.e. a top-level directory containing an __init__.py file) will not be available until the first time that package is imported. All other data files will be available as soon as Python has started.

Do not write any files to these directories at runtime, as they may be deleted when the app is upgraded. Instead, write files to os.environ["HOME"], as described in the “os” section.

Bytecode compilation#

Note

This feature requires Python on the build machine, which can be configured with the buildPython setting.

Your app will start up faster if its Python code is compiled to .pyc format, so this is enabled by default.

Compilation prevents source code text from appearing in stack traces, so during development you may wish to disable it. There are individual settings for:

For example, to disable compilation of your local source code:

defaultConfig {
    python {
        pyc {
            src false
        }
    }
}

In the case of src and pip, your buildPython must use the same bytecode format as Chaquopy itself. Usually this means it must have the same minor version, e.g. if your app’s Python version is 3.8, then buildPython can be any version of Python 3.8.

If bytecode compilation fails, the build will continue with a warning, unless you’ve explicitly set one of the pyc settings to true. Your app will still work, but its code will have to be compiled on the target device, which means it will start up slower and use more storage space.

Python standard library#

Chaquopy supports the entire Python standard library, except for the modules listed below. If you discover a problem with any other module, please let us know.

Unsupported modules#

The following modules are unsupported because they require OS features which aren’t available on Android:

The following modules are unsupported because they require libraries which we don’t currently include:

multiprocessing#

Because Android doesn’t support POSIX semaphores, most of the multiprocessing APIs will fail with the error “This platform lacks a functioning sem_open implementation”. The simplest solution is to edit your code to use multiprocessing.dummy instead.

os#

Don’t pass a simple filename to functions which write a file, as this will try to write to the current directory, which is usually read-only on Android. Instead, use a path relative to os.environ["HOME"], like this:

import os
from os.path import join
filename = join(os.environ["HOME"], "filename.txt")

You can then pass this filename to open, or any other function which writes a file.

os.environ["HOME"] is set to your app’s internal storage directory. Any files or subdirectories created in this location will persist until the app is uninstalled.

If your app is debuggable, you can read and write this directory from Android Studio using the Device File Explorer. Its path will be something like /data/data/your.application.id/files.

ssl#

The ssl module is configured to use a copy of the CA bundle from certifi version 2021.10.8. The system CA store is not used.

sys#

sys.stdout and sys.stderr are redirected to the Logcat with the tags python.stdout and python.stderr respectively. The streams will produce one log line for each call to write(), which may result in lines being split up in the log. Lines may also be split if they exceed the Logcat message length limit of approximately 4000 bytes.

By default, sys.stdin always returns EOF. If you want to run some code which takes interactive text input, have a look at the console app template.

Android Studio plugin#

To add Python editing suppport to the Android Studio user interface, you may optionally install the “Python Community Edition” plugin. However, Chaquopy isn’t integrated with this plugin, so you’ll see the warning “No Python interpreter configured for the module”, and your code will probably display many error indicators such as “Unresolved reference” and “No module named”. These are harmless: just go ahead and run your app, and if there really is an error, the details will be displayed in the Logcat.