| 1 |
.. _using-android: |
| 2 |
|
| 3 |
======================= |
| 4 |
Using Python on Android |
| 5 |
======================= |
| 6 |
|
| 7 |
Python on Android is unlike Python on desktop platforms. On a desktop platform, |
| 8 |
Python is generally installed as a system resource that can be used by any user |
| 9 |
of that computer. Users then interact with Python by running a :program:`python` |
| 10 |
executable and entering commands at an interactive prompt, or by running a |
| 11 |
Python script. |
| 12 |
|
| 13 |
On Android, there is no concept of installing as a system resource. The only unit |
| 14 |
of software distribution is an "app". There is also no console where you could |
| 15 |
run a :program:`python` executable, or interact with a Python REPL. |
| 16 |
|
| 17 |
As a result, the only way you can use Python on Android is in embedded mode – that |
| 18 |
is, by writing a native Android application, embedding a Python interpreter |
| 19 |
using ``libpython``, and invoking Python code using the :ref:`Python embedding |
| 20 |
API <embedding>`. The full Python interpreter, the standard library, and all |
| 21 |
your Python code is then packaged into your app for its own private use. |
| 22 |
|
| 23 |
The Python standard library has some notable omissions and restrictions on |
| 24 |
Android. See the :ref:`API availability guide <mobile-availability>` for |
| 25 |
details. |
| 26 |
|
| 27 |
Adding Python to an Android app |
| 28 |
------------------------------- |
| 29 |
|
| 30 |
Most app developers should use one of the following tools, which will provide a |
| 31 |
much easier experience: |
| 32 |
|
| 33 |
* `Briefcase <https://briefcase.beeware.org>`__, from the BeeWare project |
| 34 |
* `Buildozer <https://buildozer.readthedocs.io>`__, from the Kivy project |
| 35 |
* `Chaquopy <https://chaquo.com/chaquopy>`__ |
| 36 |
* `pyqtdeploy <https://www.riverbankcomputing.com/static/Docs/pyqtdeploy/>`__ |
| 37 |
* `Termux <https://termux.dev/en/>`__ |
| 38 |
|
| 39 |
If you're sure you want to do all of this manually, read on. You can use the |
| 40 |
:source:`testbed app <Android/testbed>` as a guide; each step below contains a |
| 41 |
link to the relevant file. |
| 42 |
|
| 43 |
* First, acquire a build of Python for Android: |
| 44 |
|
| 45 |
* The easiest way is to download an Android release from `python.org |
| 46 |
<https://www.python.org/downloads/android/>`__. The ``prefix`` directory |
| 47 |
mentioned below is at the top level of the package. |
| 48 |
|
| 49 |
* Or if you want to build it yourself, follow the instructions in |
| 50 |
:source:`Android/README.md`. The ``prefix`` directory will be created under |
| 51 |
:samp:`cross-build/{HOST}`. |
| 52 |
|
| 53 |
* Add code to your :source:`build.gradle <Android/testbed/app/build.gradle.kts>` |
| 54 |
file to copy the following items into your project. All except your own Python |
| 55 |
code can be copied from ``prefix/lib``: |
| 56 |
|
| 57 |
* In your JNI libraries: |
| 58 |
|
| 59 |
* ``libpython*.*.so`` |
| 60 |
* ``lib*_python.so`` (external libraries such as OpenSSL) |
| 61 |
|
| 62 |
* In your assets: |
| 63 |
|
| 64 |
* ``python*.*`` (the Python standard library) |
| 65 |
* ``python*.*/site-packages`` (your own Python code) |
| 66 |
|
| 67 |
* Add code to your app to :source:`extract the assets to the filesystem |
| 68 |
<Android/testbed/app/src/main/java/org/python/testbed/MainActivity.kt>`. |
| 69 |
|
| 70 |
* Add code to your app to :source:`start Python in embedded mode |
| 71 |
<Android/testbed/app/src/main/c/main_activity.c>`. This will need to be C code |
| 72 |
called via JNI. |
| 73 |
|
| 74 |
Building a Python package for Android |
| 75 |
------------------------------------- |
| 76 |
|
| 77 |
Python packages can be built for Android as wheels and released on PyPI. The |
| 78 |
recommended tool for doing this is `cibuildwheel |
| 79 |
<https://cibuildwheel.pypa.io/en/stable/platforms/#android>`__, which automates |
| 80 |
all the details of setting up a cross-compilation environment, building the |
| 81 |
wheel, and testing it on an emulator. |