pyside6-android-deploy: the Android deployment tool for Qt for Python¶
pyside6-android-deploy
is an easy-to-use tool for deploying PySide6 applications to different
Android architectures, namely arm64-v8a, x86_64, x86 and armeabi-v7a. This tool works similarly to
the pyside6-deploy
tool and uses the same configuration file pysidedeploy.spec
as
pyside6-deploy
to configure the deployment process. Using the deployment configuration
options either from the command line or from pysidedeploy.spec
, pyside6-android-deploy
configures the deployment to be initiated and invokes buildozer, a tool used for packaging Python
applications to Android.
The final output is a .apk or a .aab file created within the project’s source directory. The
mode option specified under the buildozer key in pysidedeploy.spec
determines whether a .apk or a .aab is created.
Warning
Currently, users are required to cross-compile Qt for Python to generate the wheels required for armeabi-v7a and x86 Andorid platforms. Instructions on cross-compiling Qt for Python for Android can be found here.
Note
pyside6-android-deploy
only works with a Unix (Linux or macOS) host at the moment.
Prerequisites¶
Before using pyside6-android-deploy
, ensure that the following prerequisites are met:
Download Android NDK and SDK¶
The NDK required corresponds to the NDK version required by the Qt version you are using. See Qt for Android for more information.
The easiest way to download the Android NDK is through a script located in the Qt for Python repository. To run the script, follow these steps:
Clone the Qt for Python repository:
git clone https://code.qt.io/pyside/pyside-setup
Run the script:
cd pyside-setup
python tools/cross_compile_android/main.py --download-only --skip-update --auto-accept-license
The script will download the Android NDK and SDK packages required into your home
directory as a directory called .pyside6-android-deploy
. pyside6-android-deploy
will
automatically detect the NDK and SDK from this cache directory.
If you want to try to download the NDK and SDK manually, you can do so from the following steps (for Qt 6.8):
Download the sdkmanager using the instructions provided in the Android Studio documentation.
Using the sdkmanager download the following packages (for Qt 6.8):
"platform-tools", "platforms;android-34", "build-tools;35.0.0"
and install the NDK using the following command (for Qt 6.8):
"ndk;26.1.10909125"
Note
The NDK version and the SDK packages required corresponds to the requirements from the Qt version you are using. See Qt for Android for more information.
Download the Qt for Python Android wheels¶
There are two ways to download the Qt for Python Android wheels:
Download the wheels from the Qt for Python downloads page.
Use qtpip download the wheels with the following command:
qtpip download PySide6 --android --arch aarch64
for the aarch64 architecture. The available architectures are aarch64 and x86_64.
How to use it?¶
Like pyside6-deploy: the deployment tool for Qt for Python, there are two different ways with which
you can deploy your PySide6 application using pyside6-android-deploy
. The only difference is
that for pyside6-android-deploy
to work, the main Python entry point file should be named
main.py
.
To deploy the application, run the following command:
pyside6-android-deploy --name "MyApp"
--wheel-pyside=path_to_downloaded_PySide_wheel
--wheel-shiboken=path_to_downloaded_Shiboken_wheel
--ndk-path=path_to_ndk
--sdk-path=path_to_sdk
The --ndk-path
and --sdk-path
options are optional if you used the script provided in the
Download Android NDK and SDK section to download the NDK and SDK.
For any subsequent deployments, you can use the pysidedeploy.spec
file to control the various
parameters of the deployment process. The command to deploy the application using the
pysidedeploy.spec
file is:
pyside6-android-deploy --config-file path_to_pysidedeploy.spec
The config-file option is optional if you are running the command from the project directory
where pysidedeploy.spec
is located.
pysidedeploy.spec¶
Like pyside6-deploy
, you can use the pysidedeploy.spec
file to control the various
parameters of the deployment process. The file has multiple sections, with each section containing
multiple keys (parameters being controlled) assigned to a value. The advantages of such a file are
mentioned here. The benefit of using the same
pysidedeploy.spec
for both pyside6-deploy
and pyside6-android-deploy
is that you can
have one single file to control deployment to all platforms.
The relevant parameters for pyside6-android-deploy
are:
- app
title
: The name of the application.project_dir
: Project directory. The general assumption made is that the project directory is the parent directory of the main Python entry point file.input_file
: Path to the main Python entry point file. Forpyside6-android-deploy
this file should be named main.py.project_file
: If it exists, this points to the path to the Qt Creator Python Project File .pyproject file. Such a file in the project directory ensures that deployment does not consider unnecessary files when bundling the executable.exec_directory
: The directory where the final executable is generated.
- python
python_path
: Path to the Python executable. It is recommended to runpyside6-android-deploy
from a virtual environment as certain Python packages will be installed onto the Python environment. However, note to keep the created virtual environment outside the project directory so thatpyside6-android-deploy
does not try to package it as well.android_packages
: The Python packages installed into the Python environment for deployment to work. By default, the Python packages buildozer and cpython are installed.
- qt
modules
: Comma-separated list of all the Qt modules used by the application. Just like the other configuration options inpysidedeploy.spec
, this option is also computed automatically bypyside6-android-deploy
. However, if you want to explicitly include certain Qt modules, the module names can be appended to this list without the Qt prefix. e.g. Network instead of QtNetworkplugins
: This field is not relevant forpyside6-android-deploy
and is only specific topyside6-deploy
. The plugins relevant forpyside6-android-deploy
are specified through theplugins
option under the android key.
- android
wheel_pyside
: Specifies the path to the PySide6 Android wheel for a specific target architecture.wheel_pyside
: Specifies the path to the Shiboken6 Android wheel for a specific target architecture.plugins
: Comma-separated list of all the Qt plugins used by the application. Just like the other configuration options inpysidedeploy.spec
, this option is also computed automatically bypyside6-android-deploy
. However, if you want to to explicitly include certain Qt plugins, the plugin names can be appended to this list. To see all the plugins bundled with PySide6, see the plugins folder in thesite-packages
on your Python where PySide6 is installed. The plugin name corresponds to their folder name. This field can be confused with theplugins
option under qt key. In the future, they will be merged into one single option.
- buildozer
mode
: Specifies one of the two modes - release and debug, to run buildozer. The release mode creates an aab while the debug mode creates an apk. The default mode is debug.recipe_dir
: Specifies the path to the directory containing python-for-android recipes. This option is automatically computed bypyside6-android-deploy
during deployment. Without the –keep-deployment-files option ofpyside6-android-deploy
, the recipe_dir will point to a temporary directory that is deleted after the final Android application package is created.jars_dir
: Specifies the path to the Qt Android .jar files that are relevant for creating the Android application package. This option is automatically computed bypyside6-android-deploy
during deployment. Just likerecipe_dir
, this field is also not relevant unless used with the –keep-deployment-files option ofpyside6-android-deploy
.ndk_path
: Specifies the path to the Android NDK used for packaging the application.sdk_path
: Specifies the path to the Android SDK used for packaging the application.local_libs
: Specifies non-Qt plugins or other libraries compatible with the Android target to be loaded by the Android runtime on startup.sdk_path
: Specifies the path to the Android SDK used for packaging the application.arch
: Specifies the target architecture’s instruction set. This option take one of the four values - aarch64, armv7a, i686, x86_64.
Command Line Options¶
Here are all the command line options of pyside6-android-deploy
:
-c/–config-file: This option is used to specify the path to
pysidedeploy.spec
explicitly.–init: Used to only create the
pysidedeploy.spec
file. Usage:pyside6-android-deploy --init
-v/–verbose: Runs
pyside6-android-deploy
in verbose mode.–dry-run: Displays the commands being run to produce the Android application package.
–keep-deployment-files: When this option is added, it retains the build folders created by buildozer during the deployment process. This includes the folder storing the python-for-android recipes, relevant .jar files and even the Android Gradle project for the application.
-f/–force: When this option is used, it assumes
yes
to all prompts and runspyside6-android-deploy
non-interactively.pyside6-android-deploy
prompts the user to create a Python virtual environment, if not already in one. With this option, the current Python environment is used irrespective of whether the current Python environment is a virtual environment or not.–name: Application name.
–wheel-pyside: Path to the PySide6 Android wheel for a specific target architecture.
–wheel-shiboken: Path to the Shiboken6 Android wheel for a specific target architecture.
–ndk-path: Path to the Android NDK used for packaging the application.
–sdk-path: Path to the Android SDK used for packaging the application.
–extra-ignore-dirs: Comma-separated directory names inside the project directory. These directories will be skipped when searching for Python files relevant to the project.
–extra-modules: Comma-separated list of Qt modules to be added to the application, in case they are not found automatically. The module name can either be specified by omitting the prefix of Qt or including it eg: both Network and QtNetwork works.
Cross-compile Qt for Python wheels for Android¶
The cross-compilation of Qt for Python wheel for a specific Android target architecture needs to be done only once per Qt version, irrespective of the number of applications you are deploying. Currently, cross-compiling Qt for Python wheels only works with a Linux host. Follow these steps to cross-compile Qt for Python Android wheels.
Download and install Qt version for which you would like to create Qt for Python wheels.
Cloning the Qt for Python repository:
git clone https://code.qt.io/pyside/pyside-setup
Check out the version that you want to build, for example 6.7. The version checked out has to correspond to the Qt version downloaded in Step 1:
cd pyside-setup && git checkout 6.7
Installing the dependencies:
pip install -r requirements.txt pip install -r tools/cross_compile_android/requirements.txt
Run the cross-compilation Python script.:
python tools/cross_compile_android/main.py --plat-name=aarch64 --qt-install-path=/opt/Qt/6.7.0 --auto-accept-license --skip-update
–qt-install-path refers to the path where Qt 6.7.0 is installed. –auto-accept-license and –skip-update are required for downloading and installing Android NDK and SDK if not already specified through command line options or if they don’t already exist in the
pyside6-android-deploy
cache. Use –help to see all the other available options:python tools/cross_compile_android/main.py --help