linuxdeploy: building AppDirs and AppImages from any application

Why AppDirs need a tool at all

linuxdeploy describes itself as an AppDir creation and maintenance tool, and the About section explains the problem it solves in a paragraph that is worth reading in full.

AppImages are a well known and popular format for distributing applications from developers to end users. The tool that creates AppImages, appimagetool, expects directories in a specific format, and that format is called an AppDir, which the AppDir specification documents. The README is careful to say that the format is not very difficult to understand, but that creating AppDirs for arbitrary applications tends to be a very repetitive task. Bundling all the dependencies properly, it adds, can be a quite difficult task.

So the two costs are repetition and dependency wrangling, and both are mechanical. Repeating a directory layout for every application is dull work, and working out which shared libraries a binary needs, and where to find them in a form that will run on someone else's machine, is tedious work that has to be redone for every release.

linuxdeploy is positioned as a tool for that middle layer. It does not create AppImages itself in the usual case; it produces and maintains AppDirs, and plugins turn those into the final bundle.

The tool is written in C++, built with CMake, MIT licensed, and lives in the linuxdeploy GitHub organisation alongside the AppImage ecosystem it serves.

The plugin system, which is the real feature

The plugin system is what separates linuxdeploy from a directory copier, and the README describes it precisely.

Plugins are separate executables that implement a CLI based plugin interface, with the specification linked. There are two kinds. Bundling plugins add resources to the AppDir, and output plugins turn the AppDir into actual bundles, for example AppImages.

That split is the design. The framework specific knowledge lives in plugins, so the core tool does not need to know what a Qt application needs or what a Java application needs. Bundling a Qt runtime is a plugin's problem, and producing an AppImage is another plugin's problem.

The discovery rules are simple and worth knowing. linuxdeploy looks for plugins in the directory containing the linuxdeploy binary, in the directory containing the AppImage when you are running from one, and in the directories on your PATH. That means a plugin is found whether you installed linuxdeploy as a system binary or as an AppImage.

The command line flags follow from that. The list-plugins option prints every plugin linuxdeploy has detected on your system. To bundle extra resources you pass the plugin option with a plugin name, and to produce an output bundle you pass the output option with a name.

One warning is in the README and it matters in practice. linuxdeploy ships with some plugins, and those bundled copies are likely out of date, so when you hit a problem the advice is to download the latest version, which takes precedence over the bundled plugin. The catalogue of official and community plugins lives in the awesome-linuxdeploy repository, and the README invites you to open an issue if you want a plugin for a specific framework or language, with existing requests collected under a plugin request label.

linuxdeploy against linuxdeployqt

The README says linuxdeploy was greatly influenced by linuxdeployqt, and the comparison it draws is specific.

linuxdeployqt employs stricter rules on AppDirs, while linuxdeploy is more flexible in use, and the README tells users of linuxdeployqt to consider switching.

The difference in approach is worth understanding, because it is not a like for like replacement. Stricter rules means a tool that produces an AppDir which always looks the same, which makes the output predictable and reviewable. Flexible means the tool will accept more shapes of input and produce more variation, which is convenient when your application does not fit the tidy case but means you have to look at what came out.

For a project that has an existing linuxdeployqt build script, the migration question is whether the flexibility is worth the re-tuning, and the README's own suggestion is to read the linuxdeploy user guide in the AppImage documentation, which covers the packaging guide for native binaries and includes an examples section.

The search path trap, and how applications must behave

The troubleshooting section contains one entry, and it is the failure that most often looks like a tool bug.

The symptom is that you bundled additional resources, but when you try to run them, either the system binary is called or the file is not found.

The cause is that linuxdeploy does not change any environment variables such as PATH. The application must search for additional resources such as icon files or executables relative to the main binary.

That is a real constraint on the application rather than on the packaging, and it is worth being precise about why. The whole point of bundling is that the AppImage should run the bundled copy rather than the one installed on the host system. If the application looks up its resources through PATH, the host's version wins, and you get the system binary running with the bundled icon missing. If it resolves them relative to its own executable, the bundled copy is the one that runs.

So an application that has to be packaged this way needs its resource lookup rewritten before linuxdeploy can package it correctly. The tool will not do that for you, and it will not warn you either, because from its point of view the AppDir is complete.

Who is already using it

The README lists an incomplete set of projects that use linuxdeploy, and the advice attached to the list is the most useful part of it. You might want to read their build scripts to see how they use linuxdeploy.

The names on that list give a sense of the range. Pext, AppImageLauncher, OpenRCT2, AppImageUpdate, appimaged, MediaElch and CPU-X, the last with a link to a description of fully automated deployment from sources with GitHub Actions.

Two of those are worth pausing on for different reasons. AppImageUpdate is part of the AppImage infrastructure itself, and appimaged is the daemon that integrates AppImages with the desktop. A packaging tool used by the runtime tooling of the same format is a reasonable signal about its maturity.

CPU-X is the case where the automation matters, because a fully automated deployment from sources in continuous integration is the scenario linuxdeploy was built for: the same commands produce the same AppDir on every release, with no human copying directories.

The documentation the README points to is the linuxdeploy user guide in the AppImage documentation, plus a native binaries packaging guide with its examples section. Those are the pages to read before writing your own build script.

Versions, builds and where the community is

The release tags are unusual. The most recent is a tag named continuous, dated 2026-08-01, described as a continuous build, and before it there are 1-alpha-20251107-1 from 2025-11-07 and 1-alpha-20250213-2 from 2025-02-13.

So the project ships a moving build alongside dated alpha releases, and the naming convention encodes the date of the build in the tag. The last push to the repository was on 2026-08-01, so the continuous tag corresponds to the current state of the branch.

The repository layout is a conventional CMake project with an include directory, a lib directory, a src directory, a tests directory, a ci directory, a cmake directory and a resources directory, plus the LICENSE file and the usual GitHub configuration.

The community channel is an IRC chatroom. The README says the easiest way to reach the developers is the AppImage channel on libera.chat, and that it is the preferred way for general feedback or questions about how to use the application. Bug reports go to GitHub issues instead, and contributions are welcome with the note that even small changes such as README fixes are appreciated.

One last thing to weigh before adopting it. linuxdeploy is infrastructure that sits between your application and its users, and its rules about AppDir layout and search paths are strict by design. If your application cannot be changed to resolve resources relative to its own binary, the packaging will look broken no matter how well the tool works.

Editorial conclusion

linuxdeploy is the right tool for a maintainer who ships a Linux application as an AppImage and has got as far as needing a repeatable AppDir layout, because it encodes the format rules once and lets plugins handle the framework specific bundling, so the build script stops being a pile of copied directories. It is the wrong choice for a one off manual bundle, where doing it by hand is quicker, and the wrong choice for a project that depends on the host system libraries rather than bundling them. Verify first that the plugins you need exist for your framework, since the plugin list is maintained in a separate awesome-linuxdeploy repository and the bundled copies are described as likely out of date, and read the troubleshooting note about search paths before you conclude the tool broke your application.

Frequently asked questions

Official sources

1. License: MIT
2. linuxdeploy/linuxdeploy on GitHub
3. Project website
4. README
5. Releases