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:

  1. Clone the Qt for Python repository:

git clone https://code.qt.io/pyside/pyside-setup

  1. 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):

  1. Download the sdkmanager using the instructions provided in the Android Studio documentation.

  2. 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:

  1. Download the wheels from the Qt for Python downloads page.

  2. 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. For pyside6-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 run pyside6-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 that pyside6-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 in pysidedeploy.spec, this option is also computed automatically by pyside6-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 QtNetwork

  • plugins: This field is not relevant for pyside6-android-deploy and is only specific to pyside6-deploy. The plugins relevant for pyside6-android-deploy are specified through the plugins 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 in pysidedeploy.spec, this option is also computed automatically by pyside6-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 the site-packages on your Python where PySide6 is installed. The plugin name corresponds to their folder name. This field can be confused with the plugins 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 by pyside6-android-deploy during deployment. Without the –keep-deployment-files option of pyside6-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 by pyside6-android-deploy during deployment. Just like recipe_dir, this field is also not relevant unless used with the –keep-deployment-files option of pyside6-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 runs pyside6-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.

  1. Download and install Qt version for which you would like to create Qt for Python wheels.

  2. Cloning the Qt for Python repository:

    git clone https://code.qt.io/pyside/pyside-setup

  3. 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

  4. Installing the dependencies:

    pip install -r requirements.txt
pip install -r tools/cross_compile_android/requirements.txt

  5. 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