Deploying Qt Applications on Linux and Windows

One of Qt’s greatest strength is also one of its major weakness. The code once deploy everywhere motto is nice when coding but once you reach the deployment step, it gets a whole different meaning.

As we are getting ready for the alpha release of Tepee3D (and almost a week late), I thought I’d post about what made us lose time.

Before creating installers for each of the platforms you are targeting, you have to run your application without the whole Qt environment on each of those.

There are two ways two proceed, either by compiling Qt statically against your executable or by delivering the necessary Qt libraries with your application.

Although the first option is the simplest of the two, it has a few caveats. First, you cannot deploy a closed sources application that way as it is against the licenses under which Qt is released.
Additionally the more Qt Modules and Add ons your application depends on, the bigger your executable will be.

We first tried the first option for Tepee3D but as we encountered errors when building statically our Qt3D fork, we switched to the second option.

First of all you need to create a package containing the necessary elements to include for your project to run. In our case this consists of shared libraries, qml and media files as well as the executable itself.


Above is the base packaged used both on Windows and Linux.

The following step is adding the necessary Qt libraries to that package. To find out which libraries you depend on you can use:

On Linux : ldd ./Your_Executable

On Windows : DependencyWalker

Once you know what are the libraries you need, copy them in a separate folder, in our case Qt_Libraries
If your application uses Qt Declarative / Qt Quick you’ll have to copy the qml directory located at the root of your QtSDK.

In addition, you’ll need to copy the platforms plugins located at QtSDK/plugins/platforms as well.

Here is a listing of our Qt_Libraries directory.
On Windows, you’ll also need to include the C++ windows runtime libraries in Qt_Libraries, (msvcp110.dll and msvcr110.dll) which can be found under Windows/system32.

Now we’re almost done, we just have to set the required path for our executable.

The easiest way to do so is by creating a shell/bat script that will set the proper variables and then call the executable.

On Linux you can use :

 export LD_LIBRARY_PATH=`pwd`/Qt_Libraries
 export QML_IMPORT_PATH=`pwd`/Qt_Libraries/qml
 export QML2_IMPORT_PATH=`pwd`/Qt_Libraries/qml
 export QT_QPA_PLATFORM_PLUGIN_PATH=`pwd`/Qt_Libraries/plugins/platforms

On Windows :

SET PATH=%cd%\Qt_Libraries;%PATH%
SET QML_IMPORT_PATH=%cd%\Qt_Libraries\qml
SET QML2_IMPORT_PATH=%cd%\Qt_Libraries\qml
SET QT_QPA_PLATFORM_PLUGIN_PATH=%cd%\Qt_Libraries\plugins\platforms

Now, test that your executable runs as planned and preferably on a clean environment.

You can finally create installers that will bundle properly your application package. We used the Qt Installer Framework and the process was quite straight forward.

Hoping it might help someone someday.

15 thoughts on “Deploying Qt Applications on Linux and Windows

  1. Pingback: Deploying Qt 5 Applications on Ubuntu 12.04 | Imagine a goblin, coding…

  2. Hi, i have a problem, when i try a run my application in a clean environment, i get a error with QtQuickControls says “cannot be loaded for a module” and “cannot load library”, i try your script (adjustally, bet don’t get result), and mark error with qtquickcontrolsprivateplugin.dll, cannot be located (i put all directory qml but i don’t get result), the best results (the messages a say is when QtQuick and QtQuick.2 are in the same level of directory)

    • Hey,
      From what I have gathered your trying to deploy on Windows a QtQuick 2 application using the new QtQuick Controls. My guess would be to first check that you have properly copied the whole qml folder present in your Qt install in your application directory. In my case it is located at C:\Qt\Qt5.2.0\5.2.0-beta1\msvc2012_64\qml. Make sure that you have a QtQuick and a QtQuick.2 subfolder in it. The QtQuickControls are in QtQuick\Controls and the qtquickcontrolsplugin.dll is right into that directory.

      Once qml has been copied in your application directory, the only thing that can be wrong is the path to your qml folder. Lets assume your app directory is MyApp. In MyApp, you should have at least your application executable MyApp.exe and the qml folder.
      Using cmd, move in your MyApp directory.
      There set the following env variables :

      SET QML_IMPORT_PATH=%cd%\qml
      SET QML2_IMPORT_PATH=%cd%\qml

      You’ll have to adjust the ones below accordingly.

      SET PATH=C:\Qt\Qt5.2.0\5.2.0-beta1\msvc2012_64\bin;%PATH%
      SET QT_QPA_PLATFORM_PLUGIN_PATH=C:\Qt\Qt5.2.0\5.2.0-beta1\msvc2012_64\bin\plugins\platforms
      SET QT_PLUGIN_PATH=C:\Qt\Qt5.2.0\5.2.0-beta1\msvc2012_64\plugins

      Then launch you app from the cmd with


      In the case it is still not working can you provide a few more details ? Is a blank window opening ? Have you tried commenting out QtQuickControls from your qml files and if so does it work ?

  3. Thanks for your reply, and i try to make this and still not working, i’m developing on Windows XP, and when execute the application appears a blank window.
    Also when i comment the code of QtQuickControls components (i only use two ComboBox and Checkbox), works.
    But i don’t look a solution and for need of time, searched and find two qml simple components CheckBox and ComboBox and try replace the QtQuickControls. But anyway thanks. Maybe in other moment i try again use a QtQuickControls, (trying in a real Xp machine without Qt or related tool). Thanks.

  4. Hi, I follwed your post and was able to make an excellent progress in my project. Thanks for taking off my load. However I had 1 question: I get an error ”
    QML AnimatedImage: Error Reading Animated Image File qrc” for a particular “.gif” file (at run time). I guess I need to copy the dependent library, “plugins/imageformats/” to my application install path, in the same hierarchy. But it doesn’t work. Are there any other libraries or plugins I need to copy? Also is there any environment variable similar to QT_QPA_PLATFORM_PLUGIN_PATH that I need to set in order for the “imageformats” to be picked?

  5. QT_PLUGIN_PATH works like a champ πŸ™‚ thanks for the quick response. But I am little unhappy about the way Qt has exposed the environmental variables. What I mean is, when we have a variable like “QT_PLUGIN_PATH”, which by the name says, “path for qt plugins”, then why do we need to again have variables, like “QT_QPA_PLATFORM_PLUGIN_PATH “, it platform plugin or imageformat plugin, ultimately it is a why is this inconsistent. also going by similar lines, if we have a variable for platform plugin, we should have had a variable for imageformat plugin also. Anyways, your post was extremely useful for me.

  6. Hi,
    Excellent work
    Just to share one issue i faced,
    I got this error once I followed your post and run the executable

    This application failed to start because it could not find or load the Qt platform plugin “xcb”.

    I found that in linux X11 systems is also required.

    I traced as,
    1. since it required xcb so I looked in to Qt_libraries/plugins/platforms directory where I found
    2. From internet I found that depends upon (type command ldd
    3. Voila! once I put in to Qt_Libraries directory and ran the script, it worked!

    Many Many thanks , Great Post !! Keep posting like this! Really Appreciate,
    Thanks Again πŸ™‚


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s