How to use linuxdeployqt


I am attempting to use linuxdeployqt to create an AppImage for my C++ QT application but am failing so far. I wish to use linuxdeployqt with a desktop file to generate the AppImage. On linuxdeployqt’s GitHub page it give this as an example:

linuxdeployqt path/to/appdir/usr/share/application_name.desktop

This issue I have here is this example seems to assume an appdir directory structure is already in place containing the desktop file, which confuses me as I assumed that linuxdeployqt would generate this directory structure.

So my questions:

  1. What should the directory structure look like and what files should be in it?
  2. Is there an example desktop file I could start with? I found the full desktop file specification a bit to much to work through.

Basically I am trying to figure out the steps required to create an AppImage once the QT application has been built.

Thanks and Regards,


linuxdeployqt expects to find a traditional Unix $PREFIX, that is, the hierarchy that normally gets installed to /usr. It works on this (by copying in dependencies and additional files) until it is an AppDir (a directory that contains everything needed to run the application on many target systems).

What should the directory structure look like and what files should be in it?

For example, if your app is myapp:

appdir/usr/share/myapp/... # optional

If qmake does not allow for make install or does not install the desktop file and icon, then you need to change your .pro file it similar to

Is there an example desktop file I could start with?

Sure, there should be plenty of examples available in nearly every desktop application project. Just search for [Desktop Entry] on GitHub. Each of the projects listed at should have one.

Basically I am trying to figure out the steps required to create an AppImage once the QT application has been built.

My recommendation is to follow almost to the letter, then go from there.

Please let us know if you find something in the documentation on unclear or confusing; we’d really like to improve it.


Thanks for the detail, there is plenty for me to work through there.

I know very little about building stuff to install on Linux so I have some research to do there. I was hoping to avoid Travis CI completely as I know nothing about this either but it looks like I may be making things more difficult for myself by avoiding it.

Anyway, I shall work through the details you have given and report back, including suggestions for documentation improvements if they make sense once I have figured it all out.

Thanks again for your help.


Indeed - if you put it on Travis CI then it is much easier for others to help you if you get stuck. Let me know once you have Travis CI going, then I can have a look at it.


I now have the Travis CI working, well it builds the binary anyway and I shall add some unit tests at a later date.

Right now I have found another issue based around my use of libpng which blocks any AppImage work until I can fix it. The problem is if I compile a copy of libpng into my code for my application to use then the system Qt libraries also use this version instead of the system version of libpng that they were compiled against. This results in some warnings and a crash as soon as the application runs.

So I now need to take a deep breath and work through this new issue. On the plus side Travis CI looks really nice and I think it will help with overall quality of the project one the unit tests are in place.

Thanks for your continued support.


Okay, I have now fixed the libpng issue with SER Player. If you could take a look at when you have time, I would appreciate any advice you can give about what I need to do next to get AppImages building with linuxdeployqt.



Hi Chris, can you use Qt 5.9? Please see for an example on how to change .travis.yml so that an AppImage gets produced and uploaded on Travis CI. Let me know if something is unclear or you are running into issues.


Thanks again for the support, we are really getting somewhere now! I can build an AppImage but it does not ask about installing a desktop file. Am I missing something obvious here?

My .travis.yml file is very similar to the one in the file in your link. However, all the files generated at the ‘script:’ stage have totally vanished by the ‘after_success:’ phase. I have added an ‘ls -l’ to my .travis.yml file to show this. Is this the expected behaviour?


That is the normal and intended behavior.

The optional appimaged daemon can be installed by the user if automatic desktop integration is desired.

Some AppImages use a wrapper script and some hackery to ask the user, but that is outside of the scope of normal AppImages or linuxdeployqt. It’s something the author of an AppImage can choose to do.


Can you give a link to this?


Actually, it seems to be there:

As for the uploading, I have sent a pull request.


Thanks for the pull request, this has been accepted and merged. The result is here:

Where is the generated AppImage being uploaded to?

Thanks again,


I have been testing with the appimaged daemon and it seems to work well, except file associations do not seem to be working. I was expecting .ser files to be associated with my application but they are not. After appimaged has done its work I see the following files installed:


My ser-player.xml file looks like this:

<?xml version="1.0" encoding="utf-8"?>
<mime-info xmlns="">
  <mime-type type="video/ser">
     <glob pattern="*.ser"/>

Should this be enough to associate .ser files with my application or have I missed something?



After some investigation I have noticed that there seems to be an error in the .desktop file that appimaged installs. The original .desktop file has this line:

Exec=ser-player %F

However, the .desktop file that is copied to ~/.local/share/applications/ has this line:


Notice that the %F part has been dropped. Is this deliberate?



Okay, so the issue I am seeing with file associations looks to be down to the desktop databases not being updated by appimaged. To make file associations work I need to:

  1. Install appimaged plus log out and in again
  2. Download the application AppImage to a supported directory.
  3. $ update-desktop-database ~/.local/share/applications/ (command line)
  4. $ update-mime-database ~/.local/share/mime/ (command line)

After this things work exactly as I would expect. Note that step 3. forces the system to analyse the .desktop files in the specified directory and update the database of which applications support which mime types.

Step 4 forces the system to analyse the mime XML files in the specified directory and update its database of mime types to file extensions.

I have been testing with Ubuntu 16.04 and both steps 3 and 4 are required after appimaged has installed the files from the AppImage.

Could appimaged be updated to do steps 3 and 4 automatically? For AppImages which require file associations I would say that appimaged currently does not work. This is at least true for Ubuntu 16.04.



Absolutely, and given what you are reporting it should be updated to do that. I have opened an issue at