appimage-test is a CLI utility that thoroughly validates Linux AppImages by verifying their compatibility and runtime stability across a matrix of different Linux distributions in isolated, ephemeral Docker containers.
Different Linux distributions ship with varying versions of system libraries (like glibc, libstdc++), security policies, and package architectures. An AppImage meant to be "universal" can easily fail on older distributions if compiled against newer libraries, or on newer distributions if it lacks necessary desktop services.
The purpose of appimage-test is to automate the QA process and catch these packaging issues before release.
For every specified Linux distribution, appimage-test validates that:
- Extraction: The AppImage can successfully extract itself (via AppRun).
- Library Compatibility: No fatal
dlopenor missing shared object errors occur during startup (e.g. missinglibssl.soorGLIBC_2.34 not found). - Desktop Integrations: The application can successfully connect to standard Linux desktop APIs without crashing. A headless X11 display is always provided; D-Bus and keyring/secret services are mocked only when you opt in via
--with dbusand--with secretsrespectively. - Process Stability: The underlying GUI application (Flutter/GTK/Qt) actually launches and stays running for a baseline timeout without immediately crashing, panicking, or segfaulting.
It accomplishes this by launching ephemeral Docker containers on-the-fly and simulating a visual display (using Xvfb) so that GUI applications don't crash when running headlessly. When --with dbus or --with secrets is passed, it also mocks system D-Bus and gnome-keyring sessions so that apps depending on those services start cleanly.
At the default info log level, each platform run reports whether the AppImage reached the baseline runtime window or exited cleanly before the timeout. That avoids treating every non-crashing run as the same kind of success when you are triaging packaging issues.
The container launch path passes the AppImage invocation as real argv instead of a flattened shell string. In practice, that means paths with spaces are supported and shell metacharacters in filenames are no longer interpreted as part of the container command.
This requires a native Linux host OS with Docker installed and running.
appimage-test [path_to_appimage] [flags][path_to_appimage]: Path to the AppImage file (relative paths are resolved to absolute).
-p,--platforms: List of Docker images to test on. Defaults to a matrix of Ubuntu, Debian, Fedora, Arch Linux, and openSUSE versions. [ubuntu:, debian:, fedora:, archlinux:, opensuse/tumbleweed:]-w,--with: Features to test with. Can be comma-separated or repeated (e.g. -w render -w dbus). [render, dbus, secrets]--log-level: Set output verbosity. [silent, info, debug, debug-system, verbose]
appimage-test supports dynamic shell autocompletion (including scraping live tags from Docker Hub when selecting platforms).
To enable it for your current session dynamically:
# For Bash
source <(appimage-test completion bash)
# For Zsh
source <(appimage-test completion zsh)This repository is a standard Go module containing a single binary. We use make to simplify building and installing, and pre-commit to maintain code quality.
To initialize the development environment, make sure pre-commit is installed and run:
make setupTo compile and install the CLI into your Go bin directory (usually ~/go/bin, which must be on your $PATH):
make installTo build the binary into a local ./bin/ folder without installing it globally:
make buildmake testTo format and vet the code:
make lintThe ## Usage section above is generated from the tool's flag definitions. To regenerate it after changing a flag:
make docsThis rewrites the content between the
<!-- BEGIN USAGE -->and<!-- END USAGE -->markers in this README.
A sample AppImage for testing appimage-test locally is included at testdata/test.AppImage.