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 | Key password, encrypted by hvigor. |
--signing-store-password <s> | QT_HARMONYOS_SIGNING_STORE_PASSWORD | Keystore password, encrypted by hvigor. |
--signing-plain-key-password <s> | QT_HARMONYOS_SIGNING_PLAIN_KEY_PASSWORD | Key password, in plain text. |
--signing-plain-store-password <s> | QT_HARMONYOS_SIGNING_PLAIN_STORE_PASSWORD | Keystore password, in plain text. |
--signing-alg <alg> | QT_HARMONYOS_SIGNING_ALG | Signature algorithm. Defaults to SHA256withECDSA. |
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 harmonydeployqt fails. With none of them set, the HAP is left unsigned.
Pass each password in one form only, and both in the same form.
With encrypted passwords, harmonydeployqt writes the signing material into the signingConfigs of the generated build-profile.json5, and hvigor signs the HAP. hvigor can only decrypt passwords that were encrypted against the material directory it finds, such as the ones DevEco Studio writes into build-profile.json5.
With plain passwords, harmonydeployqt signs the HAP with hap-sign-tool from the HarmonyOS SDK, after hvigor has packaged it. This does not depend on DevEco Studio. The tool is looked up under the SDK root, or at QT_HARMONYOS_HAP_SIGN_TOOL if that is set. It needs a Java runtime, taken from QT_HARMONYOS_JAVA, from JAVA_HOME, or from PATH.
Note: Plain passwords are passed to hap-sign-tool on its command line, which is the only input mode it supports in a non-interactive build. They are visible to other processes on the machine while it runs.
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.
