linuxdeployqt
Makes Linux applications self-contained by copying in the libraries and plugins that the application uses, and optionally generates an AppImage. Can be used for Qt and other applications
Top Related Projects
Package desktop applications as AppImages that run on common Linux-based operating systems, such as RHEL, CentOS, openSUSE, SLED, Ubuntu, Fedora, debian and derivatives. Join #AppImage on irc.libera.chat
A simple open-source disk benchmark tool for Linux distros
Quick Overview
LinuxDeployQt is a tool designed to create standalone Linux applications from Qt projects. It aims to bundle all necessary dependencies, including libraries and plugins, into a single directory or AppImage, making it easier to distribute Qt applications on Linux systems without requiring users to install additional packages.
Pros
- Simplifies the process of creating portable Linux applications
- Supports bundling Qt applications into AppImages for easy distribution
- Reduces dependency issues by including all necessary libraries
- Works with various Qt versions and can handle complex Qt projects
Cons
- May result in larger application sizes due to bundling all dependencies
- Some edge cases or complex applications might require manual intervention
- Limited to Qt-based applications
- Occasional issues with certain system libraries or specific Linux distributions
Getting Started
To use LinuxDeployQt, follow these steps:
-
Install LinuxDeployQt:
wget -c -nv "https://github.com/probonopd/linuxdeployqt/releases/download/continuous/linuxdeployqt-continuous-x86_64.AppImage" chmod a+x linuxdeployqt-continuous-x86_64.AppImage
-
Build your Qt application and navigate to its directory.
-
Run LinuxDeployQt on your application:
./linuxdeployqt-continuous-x86_64.AppImage YourApp -appimage
This will create an AppImage of your application in the current directory, which can be distributed and run on most Linux systems without additional dependencies.
Competitor Comparisons
Package desktop applications as AppImages that run on common Linux-based operating systems, such as RHEL, CentOS, openSUSE, SLED, Ubuntu, Fedora, debian and derivatives. Join #AppImage on irc.libera.chat
Pros of AppImageKit
- More comprehensive toolset for creating and managing AppImages
- Better integration with the AppImage ecosystem
- Supports a wider range of applications and use cases
Cons of AppImageKit
- Steeper learning curve due to more complex toolset
- May require more setup and configuration for basic use cases
Code Comparison
AppImageKit:
# Building an AppImage
ARCH=x86_64 appimagetool path/to/AppDir
# Extracting an AppImage
./MyApp.AppImage --appimage-extract
linuxdeployqt:
# Creating an AppImage
linuxdeployqt MyApp.desktop -appimage
# No built-in extraction functionality
Key Differences
- AppImageKit focuses on creating and managing AppImages for various applications
- linuxdeployqt specializes in deploying Qt applications as AppImages
- AppImageKit offers more advanced features and customization options
- linuxdeployqt provides a simpler, more streamlined process for Qt applications
Use Cases
- Choose AppImageKit for complex projects or when working with non-Qt applications
- Opt for linuxdeployqt when deploying Qt applications quickly and easily
Community and Support
- AppImageKit has a larger community and more extensive documentation
- linuxdeployqt is more focused on Qt developers and has a smaller, specialized user base
A simple open-source disk benchmark tool for Linux distros
Pros of KDiskMark
- Focused on disk benchmarking, providing specific functionality for measuring storage performance
- User-friendly graphical interface for easy disk performance testing
- Supports various test modes and customizable settings for comprehensive benchmarking
Cons of KDiskMark
- Limited to disk benchmarking, not a general-purpose deployment tool
- May require additional dependencies for full functionality on different Linux distributions
- Less versatile compared to linuxdeployqt's broader application deployment capabilities
Code Comparison
KDiskMark (C++):
void BenchmarkWorker::run()
{
emit progressChanged(0);
emit statusChanged(tr("Running..."));
// ... (benchmark implementation)
}
linuxdeployqt (C++):
int main(int argc, char **argv)
{
QCoreApplication app(argc, argv);
QString appDirPath = QCoreApplication::applicationDirPath();
// ... (deployment logic)
}
The code snippets show that KDiskMark focuses on benchmark execution, while linuxdeployqt deals with application deployment processes. KDiskMark's code is more specific to disk performance testing, whereas linuxdeployqt's code is geared towards managing application directories and dependencies for deployment.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
linuxdeployqt
Please note: As of 2024 , I am no longer actively working on this codebase in favor of https://github.com/probonopd/go-appimage.
This Linux Deployment Tool, linuxdeployqt
, takes an application as input and makes it self-contained by copying in the resources that the application uses (like libraries, graphics, and plugins) into a bundle. The resulting bundle can be distributed as an AppDir or as an AppImage to users, or can be put into cross-distribution packages. It can be used as part of the build process to deploy applications written in C, C++, and other compiled languages with systems like CMake
, qmake
, and make
. When used on Qt-based applications, it can bundle a specific minimal subset of Qt required to run the application.
Differences to macdeployqt
This tool is conceptually based on the Mac Deployment Tool, macdeployqt
in the tools applications of the Qt Toolkit, but has been changed to a slightly different logic and other tools needed for Linux.
- Instead of an
.app
bundle for macOS, this produces an AppDir for Linux - Instead of a
.dmg
disk image for macOS, this produces an AppImage for Linux which is quite similar to a dmg but executes the contained application rather than just opening a window on the desktop from where the application can be launched
A note on binary compatibility
To produce binaries that are compatible with many target systems, build on the oldest still-supported build system. The oldest still-supported release of Ubuntu is currently targeted, tested and supported by the team.
We recommend to target the oldest still-supported Ubuntu LTS release and build your applications on that. If you do this, the resulting binaries should be able to run on newer (but not older) systems (Ubuntu and other distributions).
linuxdeployqt
refuses to work on systems any newer than the oldest currently still-supported Ubuntu LTS release, because we want to encourage developers to build applications in a way that makes them possible to run on all still-supported distribution releases. For an overview about the support cycles of Ubuntu LTS releases, please see https://wiki.ubuntu.com/Releases. If you absolutely need to build your application on a build system newer than the oldest currently still-supported Ubuntu LTS release, then consider using go-appimage appimagetool -s deploy
(unlike linuxdeployqt
, this bundles all libraries).
linuxdeployqt
does not contain any specific workarounds for Wayland which breaks many things. For best results, do not use Wayland.
Installation
Please download linuxdeployqt-x86_64.AppImage from the Releases page and chmod a+x
it. If you would like to build linuxdeployqt
from source instead, see BUILDING.md.
Usage
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
-executable-dir=<path> : Let all the executables in the folder (recursive) 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.
-updateinformation=<update string> : Embed update information STRING; if zsyncmake is installed, generate zsync file
-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.
Simplest example
You'll need to provide the basic structure of an AppDir
which should look something like this:
âââ usr
âââ bin
â  âââ your_app
âââ lib
âââ share
âââ applications
â  âââ your_app.desktop
âââ icons
âââ <theme>
âââ <resolution>
âââ apps
âââ your_app.png
Replace <theme>
and <resolution>
with (for example) hicolor
and 256x256
respectively; see icon theme spec for more details.
Using the desktop file linuxdeployqt
can determine the parameters of the build.
Where your desktop file would look something like:
[Desktop Entry]
Type=Application
Name=Amazing Qt App
Comment=The best Qt Application Ever
Exec=your_app
Icon=your_app
Categories=Office;
- Notice that both
Exec
andIcon
only have file names. - Also Notice that the
Icon
entry does not include an extension.
Read more about desktop files in the Desktop Entry Specification 1.0.
Now you can say: linuxdeployqt-continuous-x86_64.AppImage path/to/AppDir/usr/share/applications/your_app.desktop
For a more detailed example, see "Using linuxdeployqt with Travis CI" below.
Checking library inclusion
Open in Qt Creator and build your application. Run it from the command line and inspect it with ldd
to make sure the correct libraries from the correct locations are getting loaded, as linuxdeployqt
will use ldd
internally to determine from where to copy libraries into the bundle.
QMake configuration
Important: By default, linuxdeployqt
deploys the Qt instance that qmake on the $PATH points to, so make sure that it is the correct one. Verify that qmake finds the correct Qt instance like this before running the linuxdeployqt
tool:
qmake -v
QMake version 3.0
Using Qt version 5.7.0 in /tmp/.mount_QtCreator-5.7.0-x86_64/5.7/gcc_64/lib
If this does not show the correct path to your Qt instance that you want to be bundled, then adjust your $PATH
to find the correct qmake
.
Alternatively, use the -qmake
command line option to point the tool directly to the qmake executable to be used.
Remove unnecessary files
Before running linuxdeployqt it may be wise to delete unneeded files that you do not wish to distribute from the build directory. These may be autogenerated during the build. You can delete them like so:
find $HOME/build-*-*_Qt_* \( -name "moc_*" -or -name "*.o" -or -name "qrc_*" -or -name "Makefile*" -or -name "*.a" \) -exec rm {} \;
Alternatively, you could use $DESTDIR
.
Adding icon and icon theme support
To enable icon and icon theme support you must add iconengines
as an extra Qt plugin while running linuxdeployqt
. In order for your application to locate the system theme icons, the libqgtk3.so
platform theme must also be added:
-extra-plugins=iconengines,platformthemes/libqgtk3.so
Adding extra Qt plugins
If you want aditional plugins which the tool doesn't deploy, for a variety of reasons, you can use the -extra-plugins argument and include a list of plugins separated by a comma.
The plugins deployed are from the Qt installation pointed out by qmake -v
.
You can deploy entire plugin directories, a specific directory or a mix of both.
Usage examples:
-extra-plugins=sqldrivers/libqmsql.so,iconengines/libqsvgicon.so
-extra-plugins=sqldrivers,iconengines/libqsvgicon.so
-extra-plugins=sqldrivers,iconengines,mediaservice,gamepads
Handle Qt libraries infix
If you prepared a custom Qt distribution using the option -qtlibinfix
during Qt configuration (resulting in library names such as libQt5CoreCustom.so
), you must mention this infix on linuxdeployqt
call. As an example, let's see if we configure our distribution using the infix Custom
.
On Qt build chain: configure -qtlibinfix "Custom" [...]
. This will generate Qt libraries (.so) like libQt5CoreCustom.so
So, on linuxdeployqt
call: linuxdeployqt [...] -qtlibinfix "Custom" [...]
.
If you don't mention this infix, linuxdeployqt
won't be able to detect Qt Core and Widgets libraries.
Fix for "make: Nothing to be done for 'install'"
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 https://github.com/probonopd/FeedTheMonkey/blob/master/FeedTheMonkey.pro.
Here is another simple example.
It is common on Unix to also use the build tool to install applications and libraries; for example, by invoking make install
. For this reason, qmake
has the concept of an install set, an object which contains instructions about the way a part of a project is to be installed.
Please see the section "Installing Files" on http://doc.qt.io/qt-5/qmake-advanced-usage.html.
For projects that use CMake, autotools, or meson with ninja instead of qmake
- make INSTALL_ROOT=appdir install ; find appdir/
CMake wants DESTDIR
instead:
- cmake . -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr
- make -j$(nproc)
- make DESTDIR=appdir -j$(nproc) install ; find appdir/
Some applications have the bad habit of relying on CMake versions newer than what comes with the oldest still-supported distributions. In this case, install a newer CMake with
- sudo rm -rf /usr/bin/cmake /usr/local/cmake-* /usr/local/bin/cmake || true # Needed on Travis CI; don't do this on other systems!
- wget "https://github.com/Kitware/CMake/releases/download/v3.13.2/cmake-3.13.2-Linux-x86_64.tar.gz" ; sudo tar xf cmake*.tar.gz --strip-components=1 -C /usr
Under some circumstances it may also be required to add -DCMAKE_INSTALL_LIBDIR=/usr/lib
to the cmake
call.
autotools (the dinosaur that spends precious minutes "checking...") wants DESTDIR
too but insists on an absolute link which we can feed it using readlink:
- ./configure --prefix=/usr
- make -j$(nproc)
- make install DESTDIR=$(readlink -f appdir) ; find appdir/
Caution if you encounter
qmake PREFIX=/usr CONFIG+=use_qt_paths
Here, CONFIG+=use_qt_paths
needs to be removed, otherwise it will install everything under the Qt installation paths in /opt/qt58
when using the beineri ppa.
The exception is that you are building Qt libraries that should be installed to the same location where Qt resides on your system, from where it will be picked up by linuxdeployqt
.
meson with ninja apparently wants
- meson --prefix /usr build
- ninja -C build
- DESTDIR=./appdir ninja -C build install ; find build/appdir
When using Qt from distribution packages
On Ubuntu 14.04, you will need to pass in -qmake=/usr/lib/x86_64-linux-gnu/qt5/bin/qmake
when using distribution packages.
A note on DESTDIR
According to https://dwheeler.com/essays/automating-destdir.html,
Automating DESTDIR can be a pain, so itâs best if the program supports it to start with; my package Auto-DESTDIR can automatically support DESTDIR in some cases if the program installation does not support it to begin with.
Also see https://www.gnu.org/prep/standards/html_node/DESTDIR.html for more information.
Sending Pull Requests on GitHub
linuxdeployqt
is great for upstream application projects that want to release their software in binary form to Linux users quickly and without much overhead. If you would like to see a particular application use linuxdeployqt
, then sending a Pull Request may be an option to get the upstream application project to consider it. You can use the following template text for Pull Requests but make sure to customize it to the project in question.
This PR, when merged, will compile this application on [Travis CI](https://travis-ci.org/) upon each `git push`, and upload an [AppImage](http://appimage.org/) to your GitHub Releases page.
Providing an [AppImage](http://appimage.org/) would have, among others, these advantages:
- Applications packaged as an AppImage can run on many distributions (including Ubuntu, Fedora, openSUSE, CentOS, elementaryOS, Linux Mint, and others)
- One app = one file = super simple for users: just download one AppImage file, [make it executable](http://discourse.appimage.org/t/how-to-make-an-appimage-executable/80), and run
- No unpacking or installation necessary
- No root needed
- No system libraries changed
- Works out of the box, no installation of runtimes needed
- Optional desktop integration with `appimaged`
- Optional binary delta updates, e.g., for continuous builds (only download the binary diff) using AppImageUpdate
- Can optionally GPG2-sign your AppImages (inside the file)
- Works on Live ISOs
- Can use the same AppImages when dual-booting multiple distributions
- Can be listed in the [AppImageHub](https://appimage.github.io/) central directory of available AppImages
- Can double as a self-extracting compressed archive with the `--appimage-extract` parameter
- No repositories needed. Suitable/optimized for air-gapped (offline) machines
- Decentralized
[Here is an overview](https://appimage.github.io/apps) of projects that are already distributing upstream-provided, official AppImages.
__PLEASE NOTE:__ For this to work, you need to set up `GITHUB_TOKEN` in Travis CI for this to work; please see https://github.com/probonopd/uploadtool.
If you would like to see only one entry for the Pull Request in your project's history, then please enable [this GitHub functionality](https://help.github.com/articles/configuring-commit-squashing-for-pull-requests/) on your repo. It allows you to squash (combine) the commits when merging.
If you have questions, AppImage developers are on #AppImage on irc.freenode.net.
Projects using linuxdeployqt
These projects are already using Travis CI and linuxdeployqt to provide AppImages of their builds:
- https://github.com/probonopd/ImageMagick
- https://github.com/Subsurface-divelog/subsurface/
- https://github.com/jimevins/glabels-qt
- https://travis-ci.org/NeoTheFox/RepRaptor
- https://github.com/electronpass/electronpass-desktop
- https://github.com/lirios/browser
- https://github.com/jeena/FeedTheMonkey
- https://github.com/labsquare/fastQt/
- https://github.com/sqlitebrowser/sqlitebrowser/
- https://github.com/neuro-sys/tumblr-downloader-client
- https://github.com/LongSoft/UEFITool
- https://github.com/dannagle/PacketSender
- https://github.com/nuttyartist/notes
- https://github.com/leozide/leocad/
- https://github.com/Blinkinlabs/PatternPaint
- https://github.com/fathomssen/redtimer
- https://github.com/coryo/amphetype2
- https://github.com/chkmue/MyQtTravisTemplateProject
- https://github.com/chkmue/qttravisCI_1
- https://github.com/eteran/edb-debugger
- https://github.com/crapp/labpowerqt/
- https://github.com/probonopd/linuxdeployqt/ obviously ;-)
- https://github.com/xdgurl/xdgurl
- https://github.com/QNapi/qnapi
- https://github.com/m-o-s-t-a-f-a/dana
- https://github.com/patrickelectric/mini-qml
- https://github.com/vaibhavpandeyvpz/apkstudio
These projects are using GitHub Actions and linuxdeployqt to provide AppImages of their builds:
This project is already using linuxdeployqt in a custom Jenkins workflow:
This GitHub template invokes linuxdeployqt during a GitHub CI Action:
These projects are already using linuxdeployqt:
- Autodesk EAGLE for Linux http://www.autodesk.com/products/eagle/free-download
- https://github.com/evpo/EncryptPad
- https://github.com/grahamrow/Muview2
- https://github.com/freemountain/quark/
- https://github.com/Mr0815/geraetepruefung/
This project on GitLab uses linuxdeployqt:
This project can be bundled successfully using linuxdeployqt:
Contributing
One great way to contribute is to send Pull Requests to the application projects you'd like to see use linuxdeployqt, as described above. You are also welcome to contribute to linuxdeployqt development itself. Please discuss in the forum or using GitHub issues and Pull Requests.
Contact
The developers are in the channel #AppImage on irc.freenode.net
Top Related Projects
Package desktop applications as AppImages that run on common Linux-based operating systems, such as RHEL, CentOS, openSUSE, SLED, Ubuntu, Fedora, debian and derivatives. Join #AppImage on irc.libera.chat
A simple open-source disk benchmark tool for Linux distros
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot