Linuxdeployqt vs Qt Assistant


I tried to add Qt Assistant to the AppImage of my Qt Application. I passed it as an additional executable= parameter to linuxdeployqt. When my script runs, linuxdeployqt now complains about a missing library that obviously is required by Qt Assistant through

What I don’t understand… I could not find on my Linux system at all. Qt Assistant seems to work well without.

Maybe someone can give a hint: Why does linuxdeployqt detect this library as a dependency if Qt Assistants doesn’t actually need it? What should I do to resolve the problem?


Probably Qt Assistant has a dependency on something (e.g., that has a dependency on Apparently, Qt Assistant can still run even if plugin fails to load.

linuxdeployqt uses ldd to recursively walk the dependencies of the main executable and any of the Qt libraries and plugins that get deployed. If you run it with maximum verbosity, you should be able to see which piece pulls in

A workaround may be to delete (temporarily move away) from your Qt installation before running linuxdeployqt.


That workaround sounds a bit awkward. Isn’t there a clean solution?

Why doesn’t linuxdeployqt (optionally) check if needed libraries are actually installed on the system?


Well… it does, using ldd. If they are not, it stops running and throws an error.


What would a clean solution be? The cleanest solution is to stop and throw an error if we encounter an unmet dependency.


Hmm. I am not sure about the clean solution. I have not enough knowledge in this area. I assume technically there is no difference between a mandatory dependency and an optional dependency. So linuxdeployqt can’t do it better by itself.

Since linuxdeployqt is Qt specific, could it make a difference between Qt plugins and other libraries and create warnings instead of errors for missing plugins?

Or maybe linuxdeployqt could provide an explicit command line parameter for optional libraries so the programmer can tell linuxdeployqt to include the passed dependency if it exists on the build system or skip the dependency without error if it doesn’t exist.


I played around with the -exclude-libs option of linuxdeployqt but I couldn’t solve the problem.

First I tried to exclude but ldd still fails internally (obviously -exclude-libs has no influence on the recursive dependencies).

Then I tried to exclude the plugin but assistant keeps loading it and fetches an older version from my linux installation (exiting with the beloved error “Cannot mix incompatible Qt library”).

So currently I am kind of stuck.

The only option I see is to either significantly modify my applications help system or to do the assistant dependency management manually (which kind of reduces the usability of linuxdeployqt significantly).

Any more ideas?


Currently you need to run linuxdeployqt twice and copy in the libraries in question manually in between the two runs.

Is your application on GitHub so that I could have a look?


Hm. Ok, I see. I will think about that. Running twice is easy. But managing the libs manually is nasty anyway.

No, my project is not in any public repository. What information do you need? Is something unclear about the configuration? Try to include the Qt Assistant into some random Qt AppImage and you will probably see the same error.


I finally did it that way. I also hat to move away

Still I think linuxdeployqt should provide better plugin control.