The harmonydeployqt Tool
Note: Qt for HarmonyOS is in technology preview and may change in future releases.
Packaging a Qt application for HarmonyOS involves many steps, so Qt comes with a tool that handles the work for you. Building the CMake <target>_make_hap target runs harmonydeployqt automatically, so you normally do not invoke it manually. The overall packaging and deployment process is described in Building and Deploying Qt Applications for HarmonyOS.
How it works
Like androiddeployqt, harmonydeployqt collects everything the application needs to run and assembles a deployable package:
- It gathers the application's shared library, the HarmonyOS platform plugin (
libqohos.so), the required Qt modules and plugins, and, for Qt Quick applications, the QML modules. - It places these into a HarmonyOS application template together with the metadata and permissions declared through the Qt for HarmonyOS CMake API.
- It invokes the OpenHarmony
hvigorbuild tool to assemble the final HarmonyOS Ability Package (HAP).
The settings that drive this process are passed to the tool in a JSON configuration file, which the CMake build generates for you.
Command-line arguments
The only required argument is --input. The list below is also available by passing --help to harmonydeployqt.
| Argument | Description |
|---|---|
--input <file> | JSON configuration file describing the application and the Qt installation to deploy. Required. |
--output <dir> | Output directory for the generated HarmonyOS project. |
--hvigor <path> | Path to the hvigorw script used to build the HAP. Can also be set with the QT_HARMONYOS_HVIGOR environment variable. |
--install | Install the resulting HAP to a connected device using hdc. |
--release | Build the release configuration. The default is debug. |
--no-build | Generate the HarmonyOS project but skip building the HAP. |
--test-bundle | Enable test bundle mode, which bundles all test binaries into a single HAP. |
--verbose | Enable verbose output. |
--depfile <path> | Write a dependency file for the build system to the given path. |
--depfile-base <dir> | Base directory used for relative paths in the dependency file. |
--help | Display the list of available arguments. |
Signing the HAP
A HAP must be signed before it can be installed on a device. You can provide the signing material either through command-line arguments or through the matching environment variables. When both are given, the command-line argument wins for that individual field.
| Argument | Environment variable | Description |
|---|---|---|
--signing-cert-path <p> | QT_HARMONYOS_SIGNING_CERT_PATH | Path to the .cer certificate file. |
--signing-profile <p> | QT_HARMONYOS_SIGNING_PROFILE | Path to the .p7b provisioning profile. |
--signing-store-file <p> | QT_HARMONYOS_SIGNING_STORE_FILE | Path to the .p12 keystore. |
--signing-key-alias <a> | QT_HARMONYOS_SIGNING_KEY_ALIAS | Key alias inside the keystore. |
--signing-key-password <s> | QT_HARMONYOS_SIGNING_KEY_PASSWORD | Encrypted key password. |
--signing-store-password <s> | QT_HARMONYOS_SIGNING_STORE_PASSWORD | Encrypted keystore password. |
--signing-alg <alg> | QT_HARMONYOS_SIGNING_ALG | Signature algorithm. Defaults to SHA256withECDSA. |
The passwords must be hvigor-encrypted blobs, not plain text. Signing is all-or-nothing: if any signing input is set, all six required values (the certificate, profile, keystore, key alias, key password, and keystore password) must be present. Otherwise the HAP is left unsigned.
Running the application
Install and run the resulting HAP on a connected HarmonyOS device or on the emulator. The most convenient way to deploy and debug is to open the generated project in DevEco Studio and use its run and debug tooling.
For more information about packaging and deploying a Qt application for HarmonyOS, see Building and Deploying Qt Applications for HarmonyOS.
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
