Shipping Qt on Windows — what actually breaks for you?

InsaneZhuge

I've been doing Qt/C++ on Windows for about ten years, mostly desktop apps that
get deployed to machines I can't touch. The recurring pain is never in the code —
it's in the last mile.

Things that have bitten me, roughly ordered by how much time they cost:

"no Qt platform plugin could be initialized" — the classic. Usually
platforms/qwindows.dll missing, or present but in the wrong place, or built
with a different kit than the exe.
QML app ships, launches, shows a blank window, logs nothing. Missing QML
modules that windeployqt didn't collect because --qmldir wasn't right.
Every HTTPS request fails silently. Took me a while to find: Qt 6 needs the
TLS backend plugin (qopensslbackend.dll / qschannelbackend.dll), and without
it QNetworkAccessManager just returns generic errors with no clue why.
0xc000007b on the customer machine. 32/64-bit mismatch, or a wrong-arch
vcruntime140.dll already sitting somewhere in PATH.
Runs fine on my box, missing MSVC redistributable on theirs.
Antivirus flags the exe. Unsigned binary.
Fonts and widget styles look completely different on another machine —
missing styles/ plugin.

My current process is: build, run windeployqt, then manually walk the deploy
folder against a checklist I've accumulated over years, then test on a clean VM.
It works, but it lives entirely in my head and it's easy to skip a step when
I'm in a hurry.

So, for those of you shipping Qt on Windows:

Which of these have bitten you, and which one costs you the most time?
What's the failure mode that is NOT on my list? I'm fairly sure I've just
been lucky with a few.

Not selling anything here — I'm trying to figure out whether the checklist in
my head is a shared problem or just my own paranoia.

SGaist

Hi,

What were you using to process your application before shipping it for deployment ?

SimonSchroeder

First of all, we are not using QML in our app, yet. So, I probably have fewer problems.

The MSVC distributable is a little bit annoying. In the past we solved it through the NSIS installer. I believe it can have a dependency to the MSVC distributable. But, at some point we also ran into problems. We then decided to link MSVC libs statically. This is also quite annoying because not every 3rd party library has an easy option to link against MSVC statically. I believe CMake only got that option very recently. And package managers usually don't help you with that.

We had a DLL chaos with a different program and so for our main software we decided to just also link Qt statically. With the LGPL this gives additional requirements that you need to provide users of your software a way to link with their own Qt library. But, this has never happened so far (and we cannot give support or warranty for software we didn't fully compile). This also means that we needed to compile OpenSSL statically and it is linked into Qt. So, we just have a single executable to distribute and no DLLs. And any additional files we try to put into a .qrc file. This handles your points 1., 3., 4., and 5. I don't know how this would work properly with QML. (BTW, our program has ~380k lines of code + another ~80k lines of code in our own libs + 3rd party libraries besides Qt; the final executable is currently 62MB.)

We started signing our executables because of antivirus problems. We used the cheaper certificates, so Windows still sometimes complains (but at least it will also mention our company name). It is quite annoying because when we last renewed our certificate, having the private key as a file was no longer allowed and it now has to be a hardware key. This restricts signing to a single computer in our CI/CD. And we haven't worked out everything perfectly: In order to avoid being flagged by antivirus again when you renew your certificate, you should have an overlapping period where you sign your software both with the old and the new certificate. We haven't done that, yet. Also, if I have done my research properly, Mozilla and other companies are pushing for much shorter periods where the certificate is valid. We still have a certificate valid for 3 years, but I guess in the future it will only be weeks.

You should really figure out how to properly deploy your software and then write a script that does it (or have AI write you a script). Once you have tested it on a clean VM, it should be reliable enough to just trust the script. (But adding files to your project still might fail on other users' machines in the future.)

hskoglund

Totally agree with previous speaker, i.e. if you want to keep your sanity: static link all the things.

(I've done a similar journey, like when shipping a dynamic build everything was fine on a vanilla customer PC, but if they happened to have Qt installed, then interestiing problems/collisions would occur :-)

Just want to add re. certificates. You need them. But a hardware key can set you back 500 US$ and as Simon mentions above, can only be used on a single computer.

Instead I use Microsoft Azure Trusted Signing, costs 10 US$ every month but it can be used on multiple PCs :-)
One odd thing is that their certificates only are valid for 3 days, but don't worry they will work for you. For an in depth explanation look here