How to Deploy Your Qt Cross-Platform Applications to Linux Operating System With linuxdeployqt
This tutorial explains the manner to deploy cross-platform projects you made with the Qt framework ( Qt Core, Qt Widgets, and Qt Quick alike) to Linux Operating Systems using linuxdeployqt

I used this environment for these demonstrations
Operating System information

Qt Code on Qt Creator

Code sample
The lines of code show the construction of a custom Widget and appear in the following Udemy course:
If you are serious about learning Qt, I recommend following along Daniel Gakwaya’s courses on Udemy.
At this point, the preparations are completed. Let’s start the thing.
Step 0. Build the Qt code in Release Mode


Locate the Qt Application in the Release Build Directory



There are two ways to proceed further to achieve the deployment on the Linux Operating System. That means your application will have all the necessary Qt libraries at its disposal, irrespective of the Qt framework installation on that machine. End user could simply run the application you deployed.
Deployment on Linux using linuxdeployqt
Step 1 . Set up the deployment directory

Step 2. Go to linuxdeployqt github

Step 3. Download the latest release of linuxdeployqt from github
The first option to download the release:

The second option to download the release:


Download the .AppImage

Step 4. Grant execution rights to the downloaded file


Step 5. Execute the file through terminal shell command
Potential Errors and their solution
Notes: As of November 23rd, 2020, the moment I am editing this, download and use the Release 5 of the linuxdeployqt .AppImage.
Otherwise, you will get the following errors when executing it :
georgeca@georgeca-VirtualBox:~/Downloads$ ./linuxdeployqt-7-x86_64.AppImage
linuxdeployqt 6 (commit d41e234), build 724 built on 2020-07-31 15:51:47 UTC
ERROR: The host system is too new.
Please run on a system with a glibc version no newer than what comes with the oldest
currently still-supported mainstream distribution (xenial), which is glibc 2.23.
This is so that the resulting bundle will work on most still-supported Linux distributions.
For more information, please see
https://github.com/probonopd/linuxdeployqt/issues/340same error for linuxdeployqt-6-x86
georgeca@georgeca-VirtualBox:~/Downloads$ ./linuxdeployqt-6-x86_64.AppImage
linuxdeployqt 5 (commit 37631e5), build 631 built on 2019-01-25 22:47:58 UTC
ERROR: The host system is too new.
Please run on a system with a glibc version no newer than what comes with the oldest
still-supported mainstream distribution, which currently is glibc 2.20.
This is so that the resulting bundle will work on most still-supported Linux distributions.
For more information, please see
https://github.com/probonopd/linuxdeployqt/issues/340Executing the .AppImage file provides you with hints about how to use it
georgeca@georgeca-VirtualBox:~/Downloads$ ./linuxdeployqt-5-x86_64.AppImage
linuxdeployqt 4 (commit 8b3ded6), build 571 built on 2018-10-07 20:58:12 UTC
Usage: linuxdeployqt <app-binary|desktop file> [options]
Options:
-always-overwrite : Copy files even if the target file exists.
-appimage : Create an AppImage (implies -bundle-non-qt-libs).
-bundle-non-qt-libs : Also bundle non-core, non-Qt libraries.
-exclude-libs=<list> : List of libraries which should be excluded,
separated by comma.
-ignore-glob=<glob> : Glob pattern relative to appdir to ignore when
searching for libraries.
-executable=<path> : Let the given executable use the deployed libraries
too
-extra-plugins=<list> : List of extra plugins which should be deployed,
separated by comma.
-no-copy-copyright-files : Skip deployment of copyright files.
-no-plugins : Skip plugin deployment.
-no-strip : Don't run 'strip' on the binaries.
-no-translations : Skip deployment of translations.
-qmake=<path> : The qmake executable to use.
-qmldir=<path> : Scan for QML imports in the given path.
-qmlimport=<path> : Add the given path to QML module search locations.
-show-exclude-libs : Print exclude libraries list.
-verbose=<0-3> : 0 = no output, 1 = error/warning (default),
2 = normal, 3 = debug.
-version : Print version statement and exit.
linuxdeployqt takes an application as input and makes it
self-contained by copying in the Qt libraries and plugins that
the application uses.
By default it deploys the Qt instance that qmake on the $PATH points to.
The '-qmake' option can be used to point to the qmake executable
to be used instead.
Plugins related to a Qt library are copied in with the library.
See the "Deploying Applications on Linux" topic in the
documentation for more information about deployment on Linux.Step 6. Save the image file which will serve as the application’s icon
Step 7. Write the .desktop text file and save it in the deployment directory, alongside the executable

Here are the specifications for writing .desktop files: https://specifications.freedesktop.org/desktop-entry-spec/latest/

[Desktop Entry]
Type=Application
Name=WaterMonitoringSystem
Comment=This is an application that measures levels in the tank and shows warning signals as traffic lights
Exec=WaterLevelMonitoringSystem
Icon=penguinStep 8. Run the linuxdeployqt with the path to the executable and the other relevant arguments
Potential error: missing qmake in $PATH variable
georgeca@georgeca-VirtualBox:~/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt$ cd ~
georgeca@georgeca-VirtualBox:~$ cd Downloads/
georgeca@georgeca-VirtualBox:~/Downloads$ ls -lh
total 360M
-rw-rw-r-- 1 georgeca georgeca 1,2K sep 10 15:44 0001-georges-led-pin9_23.patch
-rw-rw-r-- 1 georgeca georgeca 241M sep 8 09:24 eclipse-cpp-2020-06-R-linux-gtk-x86_64.tar.gz
-rw-rw-r-- 1 georgeca georgeca 105M sep 8 09:38 gcc-linaro-7.5.0-2019.12-x86_64_arm-linux-gnueabihf.tar.xz
-rwxrwxr-x 1 georgeca georgeca 14M nov 17 12:07 linuxdeployqt-5-x86_64.AppImage
georgeca@georgeca-VirtualBox:~/Downloads$ ./linuxdeployqt-5-x86_64.AppImage ~/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/WaterLevelMonitoringSystem
linuxdeployqt 4 (commit 8b3ded6), build 571 built on 2018-10-07 20:58:12 UTC
Not using FHS-like mode
app-binary: "/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/WaterLevelMonitoringSystem"
appDirPath: "/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt"
relativeBinPath: "WaterLevelMonitoringSystem"
ERROR: qmake not found on the $PATHSolution: Add qmake path to the environment $PATH variable



Run the terminal command to add its path to the $PATH environment variable
Get the directory path towards the ‘bin’ directory:
georgeca@georgeca-VirtualBox:~/Qt/5.14.2/gcc_64$ cd bin/
georgeca@georgeca-VirtualBox:~/Qt/5.14.2/gcc_64/bin$ pwd
/home/georgeca/Qt/5.14.2/gcc_64/binAdd to the $PATH variable
georgeca@georgeca-VirtualBox:~/Qt/5.14.2/gcc_64/bin$ export PATH=/home/georgeca/Qt/5.14.2/gcc_64/bin/:$PATHAfter adding the qmake path, the environment variable $PATH is going to look like this:

Finally:
OPTION 1: Run linuxdeployqt to deploy the necessary Qt libraries inside the deployment directory

The outcome is:

The directories in the deployment contain all the necessary Qt libraries to run the application:
georgeca@georgeca-VirtualBox:~/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt$ tree -L 3 .
.
├── AppRun -> WaterLevelMonitoringSystem
├── lib
│ ├── libicudata.so.56
│ ├── libicui18n.so.56
│ ├── libicuuc.so.56
│ ├── libQt5Core.so.5
│ ├── libQt5DBus.so.5
│ ├── libQt5Gui.so.5
│ ├── libQt5Network.so.5
│ ├── libQt5QmlModels.so.5
│ ├── libQt5Qml.so.5
│ ├── libQt5Quick.so.5
│ ├── libQt5VirtualKeyboard.so.5
│ ├── libQt5Widgets.so.5
│ └── libQt5XcbQpa.so.5
├── plugins
│ ├── imageformats
│ │ ├── libqgif.so
│ │ ├── libqicns.so
│ │ ├── libqico.so
│ │ ├── libqjpeg.so
│ │ ├── libqtga.so
│ │ ├── libqtiff.so
│ │ ├── libqwbmp.so
│ │ └── libqwebp.so
│ ├── platforminputcontexts
│ │ ├── libcomposeplatforminputcontextplugin.so
│ │ ├── libibusplatforminputcontextplugin.so
│ │ └── libqtvirtualkeyboardplugin.so
│ ├── platforms
│ │ └── libqxcb.so
│ └── xcbglintegrations
│ ├── libqxcb-egl-integration.so
│ └── libqxcb-glx-integration.so
├── qt.conf
├── translations
│ ├── qt_ar.qm
│ ├── qt_bg.qm
│ ├── qt_ca.qm
│ ├── qt_cs.qm
│ ├── qt_da.qm
│ ├── qt_de.qm
│ ├── qt_en.qm
│ ├── qt_es.qm
│ ├── qt_fi.qm
│ ├── qt_fr.qm
│ ├── qt_gd.qm
│ ├── qt_he.qm
│ ├── qt_hu.qm
│ ├── qt_it.qm
│ ├── qt_ja.qm
│ ├── qt_ko.qm
│ ├── qt_lv.qm
│ ├── qt_pl.qm
│ ├── qt_ru.qm
│ ├── qt_sk.qm
│ ├── qt_uk.qm
│ └── qt_zh_TW.qm
├── WaterLevelMonitoringSystem
└── WaterLevelMonitoringSystem.desktop.desktop
7 directories, 53 filesOPTION 2: Create a single .AppImage executable file to deploy the Qt Application on Linux

georgeca@georgeca-VirtualBox:~/Downloads$ ./linuxdeployqt-5-x86_64.AppImage ~/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/WaterLevelMonitoringSystem -appimage
linuxdeployqt 4 (commit 8b3ded6), build 571 built on 2018-10-07 20:58:12 UTC
Not using FHS-like mode
app-binary: "/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/WaterLevelMonitoringSystem"
appDirPath: "/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt"
relativeBinPath: "WaterLevelMonitoringSystem"
WARNING: "/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/qt.conf" already exists, will not overwrite.
appimagetool, continuous build (commit d185526), build 1855 built on 2018-10-07 20:18:45 UTC
Desktop file: /home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/WaterLevelMonitoringSystem.desktop.desktop
Name: WaterLevelMonitoringSystem
Icon: penguin
Exec: WaterLevelMonitoringSystem
Comment: This is an application that measures levels in the tank and shows warning signals as traffic lights
Type: Application
Categories entry not found in desktop file
Categories: (null)
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/plugins/xcbglintegrations/libqxcb-glx-integration.so used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/plugins/xcbglintegrations/libqxcb-egl-integration.so used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/plugins/imageformats/libqgif.so used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/plugins/imageformats/libqtiff.so used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/plugins/imageformats/libqico.so used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/plugins/imageformats/libqjpeg.so used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/plugins/imageformats/libqwbmp.so used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/plugins/imageformats/libqwebp.so used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/plugins/imageformats/libqicns.so used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/plugins/imageformats/libqtga.so used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/plugins/bearer/libqconnmanbearer.so used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/plugins/bearer/libqnmbearer.so used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/plugins/bearer/libqgenericbearer.so used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/plugins/platforminputcontexts/libqtvirtualkeyboardplugin.so used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/plugins/platforminputcontexts/libibusplatforminputcontextplugin.so used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/plugins/platforminputcontexts/libcomposeplatforminputcontextplugin.so used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/plugins/platforms/libqxcb.so used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libXdmcp.so.6 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libk5crypto.so.3 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libQt5Network.so.5 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libxcb-glx.so.0 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libgssapi_krb5.so.2 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libQt5XcbQpa.so.5 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libGLdispatch.so.0 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libkrb5support.so.0 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libQt5DBus.so.5 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libxkbcommon.so.0 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libXau.so.6 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libQt5Widgets.so.5 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libpng16.so.16 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libkrb5.so.3 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libgcrypt.so.20 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libXext.so.6 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libsystemd.so.0 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libgthread-2.0.so.0 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libxkbcommon-x11.so.0 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libbsd.so.0 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libQt5QmlModels.so.5 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libQt5Qml.so.5 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libicudata.so.56 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libxcb-xfixes.so.0 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libxcb-xkb.so.1 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libQt5Quick.so.5 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libdbus-1.so.3 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libQt5VirtualKeyboard.so.5 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libicuuc.so.56 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libQt5Gui.so.5 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/liblzma.so.5 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libicui18n.so.56 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libQt5Core.so.5 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/liblz4.so.1 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libGLX.so.0 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libX11-xcb.so.1 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/lib/libpcre.so.3 used for determining architecture x86_64
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt/WaterLevelMonitoringSystem used for determining architecture x86_64
Using architecture x86_64
App name for filename: WaterLevelMonitoringSystem
/home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt should be packaged as WaterLevelMonitoringSystem-x86_64.AppImage
Deleting pre-existing .DirIcon
Creating .DirIcon symlink based on information from desktop file
Generating squashfs...
Size of the embedded runtime: 187784 bytes
mksquashfs commandline: /tmp/.mount_linuxdBLwf77/usr/bin/../lib/appimagekit/mksquashfs /home/georgeca/Qt-Tutorials/Deployment/deploy-with-linuxdeployqt WaterLevelMonitoringSystem-x86_64.AppImage -offset 187784 -comp gzip -root-owned -noappend -mkfs-fixed-time 0
Parallel mksquashfs: Using 2 processors
Creating 4.0 filesystem on WaterLevelMonitoringSystem-x86_64.AppImage, block size 131072.
[===========================================================================================================================================================================================-] 730/730 100%
Exportable Squashfs 4.0 filesystem, gzip compressed, data block size 131072
compressed data, compressed metadata, compressed fragments, compressed xattrs
duplicates are removed
Filesystem size 32075.81 Kbytes (31.32 Mbytes)
37.54% of uncompressed filesystem size (85453.68 Kbytes)
Inode table size 3593 bytes (3.51 Kbytes)
49.61% of uncompressed inode table size (7243 bytes)
Directory table size 1441 bytes (1.41 Kbytes)
44.16% of uncompressed directory table size (3263 bytes)
Number of duplicate files found 8
Number of inodes 141
Number of files 105
Number of fragments 16
Number of symbolic links 2
Number of device nodes 0
Number of fifo nodes 0
Number of socket nodes 0
Number of directories 34
Number of ids (unique uids + gids) 1
Number of uids 1
root (0)
Number of gids 1
root (0)
Embedding ELF...
Marking the AppImage as executable...
Embedding MD5 digest
Success
Please consider submitting your AppImage to AppImageHub, the crowd-sourced
central directory of available AppImages, by opening a pull request
at https://github.com/AppImage/appimage.github.ioOutcome: .AppImage generated alongside linuxdeployqt file

Upon double clicking the .AppImage file, one can run the file.

Alternative solutions
Use the following alternative method to deploy Qt cross-platform applications to Linux Operating System:
In case you wish to deploy your application to Windows Operating System, feel free to use either solution of the following:
If you consider my articles to be helping you, you could support me in writing the next articles by using this page.
Thank you.






