Automatic QML import by Qt deployment tools

There was a small problem with Qt’s deployment tools that could, however, cause some struggle for beginners. windeployqt, macdeployqt and linuxdeployqt could not add a third-party Qt Quick module (i.e. one that is not located inside Qt’s installation directory, like Kirigami) to the resulting bundle.

It was, of course, possible to workaround the issue by copying the missing files to their expected locations with a script or manually. For non-systemwide Qt installations, there was also an option of installing the libraries by side with Qt’s own modules. However, these are still platform-dependent workarounds we shouldn’t rely on long-term.

I faced this issue when trying to package Kaidan, a Qt Quick XMPP client, as an AppImage. After a discussion with linuxdeployqt’s contributors and some research, I found that internally the tool uses qmlimportscanner to locate the imported modules, but only passes QT_INSTALL_QML (Qt’s own modules location) to the scanner. It was clearly missing an option to list custom import paths, like -qmlimport. That was easy to fix, and so I did.

linuxdeployqt is a fork of macdeployqt, and so I decided it makes sense to upstream my changes. I made sure I’m not missing anything, then started a Gerrit revision.

While my changes were pending approval, I looked into windeployqt’s sources and submitted a matching revision to that tool.

When all three commits had been merged, I documented my changes.


Starting with Qt 5.13 there’ll be an option in Qt deployment tools (-qmlimport) to specify custom import paths for Qt Quick libraries. As a nice bonus, this option also allows to choose between multiple versions of a library installed at different locations. For a more in-depth explanation of the change, please refer to this comment.

Contributing to Qt is not that difficult, and making even a small useful change feels so nice 🙂

Kaidan running on Apple macOS

If you hesitated to try Kirigami in your project because of deployment quirks, give it a go now! Join us on IRC or Matrix, take a look at the docs and have fun creating! 😀

Leave a Reply