Qt is relocatable

As of version 5.14.0 Qt is relocatable, i.e. it is possible to move the Qt installation to a different directory without breaking functionality or loading of plugins.

OK, what’s in it for me?

Let’s slip into the role of the Qt build master of a Windows project. You’re the one who knows all configure arguments by heart. You know which optimization screw to turn and which unneeded feature to turn off.
Your Qt build is perfectly tailored to the project and you’re providing a zip file containing the Qt installation.

You’re running

configure -prefix C:/Qt/5.12.6 ...more options...
jom install
zip -r X:\shared_stuff\qt-5.12.6.zip C:\Qt\5.12.6

Then your teammates extract the archive to exactly the same location, and everything works fine.

Now, for whatever reason, Joe Developer must extract the Qt installation to some other drive/directory.
The Qt in that different directory is dysfunctional. QMake won’t work properly. Plugins cannot be loaded. Qt assets cannot be found.

Why is everything broken?

Historically, Qt’s configure will bake the installation directory into the qmake executable and the Qt5Core library. The logic in QLibraryInfo tries to locate plugins, assets and mkspecs below the hard-coded prefix, which is always what you passed to configure with the -prefix argument.

And in Qt 5.14 moving the installation directory works?

Oh yes! Since Qt 5.14.0 the installation prefix can be automatically determined by the location of the Qt5Core library or the executable itself without relying on hard-coded paths.

This automatism is controlled at the time when Qt is configured via the relocatable feature.
This feature is on by default for non-static builds of Qt.

If you need a relocatable static build, turn on the feature manually:

configure -static -feature-relocatable ...

The caveat of relocatable static builds is that Qt-internal translations are not picked up automatically.
You will have to deploy Qt’s translation files together with your application.

This difference to the non-relocatable build is the reason why relocatable is off by default for static builds.

No Sir, I don’t like it! Can I turn it off?

Of course you can.

configure -no-feature-relocatable ...

will bring back the old behavior.

Linux distributions, for example, don’t have the need for a relocatable Qt and can turn off the feature.


QTBUG-14150 is the original issue where the effort was tracked.

Commit 4ac872639ed0dd3ae6627e05bdda821f7d128500 in qtbase introduced the relocatable feature.

Blog Topics: