This page contains information particular to building Qt applications for and running them on the Android platform. Qt supports Android versions 4.1 (API level 16) or later.

Android Development in Qt Creator

The easiest way to develop with Qt for Android is to use Qt Creator. When you apply a Qt for Android Kit to a Qt Creator project, it will create and maintain a set of files which are required to make your application run on Android.

The files added to your project are:

• .java files will serve as the entry point into your application and automatically load Qt to execute the native code in your application
• AndroidManifest.xml which provides meta-information about your application
• Other XML files detailing the dependencies of your application
• Resource files
• Depending on the deployment method selected in Qt Creator, additional files like libraries and QML files can be included in the project.

Qt Creator adds these files in a subdirectory of your project called android. The contents of the android folder is used as basis for your app's distributable application package.

Application Package

On Android, apps are distributed to devices in packages called APK.

For distributing apps in Google Play, a different format called AAB is used instead.

Although Qt Creator supports building both these package formats for you, you could also build them manually when needed. To do so, ensure that the necessary packages and build files are in place. For more detailed information about how the packaging is done, see Deploying an Application on Android.

Plugins and Imports Special Considerations

If an application uses plugins that depend on other modules, these modules must be listed in the application's dependencies. This is because Qt Creator does not know ahead of time which plugins your application will end up loading.

For example, if a plugin depends on Qt Multimedia, then the Qt Multimedia module must explicitly be made a dependency of the application, otherwise the plugin cannot be loaded. You can do this by adding it to the application's .pro file:

QT += multimedia

The automatic deployment tool detects any dependencies on QML modules that are imported from the application's code, but in special case (for instance when QML code is generated by the C++ code), this is not possible. If this generated code imports any special QML modules, they are not detected by the deployment tool and therefore will not be included in the application bundle.

In these cases, you must add "dummy" QML code importing the same modules as the generated code, so that the automated tool detects the dependencies.

Text Special Considerations

Because of a bug in some OpenGL drivers, the mechanism used by Qt to cache text glyphs does not work as expected on all Android devices, causing text to appear scrambled. To remedy this, a workaround is in place, which increases memory consumption and can also affect text rendering performance. Before Qt 5.3.2, the workaround was enabled only for a particular set of devices. It is now used by default on all devices.

You can disable the workaround by setting the QT_ANDROID_DISABLE_GLYPH_CACHE_WORKAROUND environment variable to 1. You should do so only after verifying that text appears correctly on all targeted devices.

OpenGL Special Considerations

Modern devices often support OpenGL ES 3.0 or 3.1 in addition to 2.0. To get a suitable OpenGL context, set the requested version via QSurfaceFormat::setVersion(). Note however that the header files are only available in recent API levels, for example to include gl31.h, you need to target API level 21. Keep in mind also that using OpenGL ES 3.x features will result in the application breaking on older devices that only support 2.0.

Multimedia Special Considerations

The Qt Multimedia Widgets module is not supported on Android, which means video display is only available using the VideoOutput and the Video QML Type.

Assets File System

Qt for Android provides a special, virtual file system which is based on the assets mechanism in Android. Files that are put under assets in the android folder created by Qt Creator, will be packaged as part of your application package. These can be accessed in Qt by prefixing the paths with assets:/. For instance, to access the image logo.png in the folder assets/images, you can use QPixmap("assets:/images/logo.png").

If using the assets mechanism is not required for your app, the recommended way of distributing resources with your Qt app is to use The Qt Resource System, which is a cross-platform mechanism for distributing resources with your app.

Supported Architectures

Qt for Android currently has binaries for armv7a, arm64-v8a, x86 and x86-64.

If you want to support several different ABIs in your application, the recommendation is to build an Application App Bundle (AAB) containing binaries for each of the ABIs. Based on this, Google Play generates optimized Application Packages (APK) for the device issuing the download request.

The Application App Bundle is generated by Qt Creator, if the corresponding checkbox for this is selected in the project settings. It can also be built from the command line by using the "aab" Makefile target.

% make aab

Known Issues

Due to a bug on some devices, when you turn off predictive text with ImhNoPredictiveText, this property will be ignored and predictive text will still be enabled. To work around this, set the QT_ANDROID_ENABLE_WORKAROUND_TO_DISABLE_PREDICTIVE_TEXT environment variable to 1. However, one side effect is that this environment variable can cause a problem with other keyboards such as Gboard. If you use a language like Japanese, with Gboard, only a QWERTY keyboard is displayed. This environment variable is queried each time the keyboard is displayed, so it's possible to toggle the workaround on and off, as necessary.