AppImage Manager

Manage your AppImages inside your user environment — no root required.

The tool tracks installed AppImages and lets you list, update, and remove them afterwards. See how it works.

It ships with two frontends that share the same core logic:

• appimage-manager-tui.sh — an interactive TUI (powered by gum) for installing, listing, and uninstalling AppImages.
• appimage-manager.sh — a scriptable command-line interface.

---

Features

• No root — writes only to your user directories.
• App menu integration — generates a freedesktop-compliant .desktop launcher.
• Icon support — uses a provided icon, or extracts one from the AppImage when possible.
• Full lifecycle — install, list, update, and uninstall AppImages.
• Safe defaults — validates inputs, handles spaces, and avoids destructive changes unless --force is used.
• Smart launcher — the generated wrapper detects a missing libfuse2 and auto-falls-back to --no-sandbox if the first launch fails (helps on Ubuntu 24.04).
• Self-contained distribution — make bundle inlines the library so each entrypoint can be shipped as a single file.

Requirements

• Linux desktop with a freedesktop-compatible menu, i.e., through XDG Desktop Portal.
• Bash 4+.
• gum (required for the TUI; not needed for the CLI). Both gum 2.x and older builds such as 0.16 (Fedora 43) work: picker padding is applied only when the running gum supports it.
• Optional: file as a fallback for icon type detection (usually preinstalled; the type is normally determined from the filename or content magic bytes).
• Development only: shellcheck and shfmt (for make test / make fmt).

Installation

git clone https://github.com/brunomnsilva/appimage-manager
cd appimage-manager
make install

make install bundles the library and copies both commands into ~/.local/bin (override with make install PREFIX=/usr/local). Ensure that directory is on your PATH, then run appimage-manager-tui or appimage-manager. Remove them again with make uninstall.

Prefer not to build? Download the prebuilt appimage-manager and appimage-manager-tui from the latest release and drop them in a directory on your PATH.

Project structure

appimage-manager.sh          # CLI entrypoint
appimage-manager-tui.sh      # TUI entrypoint (gum)
lib/core.sh                  # shared library (no side effects)
scripts/build.sh             # bundles lib/core.sh into dist/ entrypoints
Makefile                     # bundle / test / lint / fmt / install / uninstall / clean
tests/run-tests.sh           # headless test harness

Quick start

Run directly from a clone (without installing):

TUI

chmod +x appimage-manager-tui.sh
./appimage-manager-tui.sh

The TUI walks you through an install, or lets you list and uninstall existing apps from the main menu.

CLI

chmod +x appimage-manager.sh
./appimage-manager.sh ~/Downloads/Obsidian.AppImage

This copies the AppImage to ~/Applications/, writes ~/.local/share/applications/<slug>.desktop, and installs an icon when one can be extracted.

If you ran make install, use the installed commands instead: appimage-manager-tui and appimage-manager.

TUI usage

The main menu offers:

• Install an AppImage — file picker, then prompts for name, comment, category, MIME types, launch args, and icon. A valid AppImage is extracted once and its bundled .desktop is read to prefill name, comment, categories, and MIME types as suggestions you can edit. If the payload bundles an icon, the icon step offers Auto-extract (icon is bundled); otherwise it warns that no icon is bundled and offers a custom icon or none. A file that is not a valid AppImage (e.g. a standalone binary such as Winbox) triggers a warning and offers to install it anyway; inspection is skipped.
• List installed — shows a table of installed apps (name, path, status).
• Update an AppImage — pick an installed app and a newer AppImage; the payload is replaced in place, keeping the name, menu entry, launch flags, and icon (or choose a new icon). A warning reminds you to back up the current file first.
• Uninstall — select an app and confirm removal.
• Help — brief description.
• Exit — quit.

Category presets

The installer presents a single-select list of common freedesktop categories (Utility, Development, Office, Graphics, AudioVideo, Network, Game, Education, Science, System) plus Custom… for free-form input.

Launch-args presets

Instead of typing flags, pick from common presets (multi-select) or choose Custom…:

Preset	Value
--no-sandbox	--no-sandbox
--disable-gpu	--disable-gpu
--disable-dev-shm-usage	--disable-dev-shm-usage
Wayland (auto)	--ozone-platform-hint=auto
Wayland (native)	--enable-features=UseOzonePlatform,WaylandWindowDecorations --ozone-platform-hint=auto

CLI options

Option	Description
--name NAME	Display name and base filename (default: from the AppImage filename)
--categories CATS	Desktop menu categories (default: Utility;)
--mime-types TYPES	Semicolon-separated MIME types the app handles (e.g. image/png;text/plain;), written to MimeType=
--comment TEXT	One-line description for the launcher
--icon PATH	Custom icon file (.png or .svg)
--exec-args ARGS	Extra args appended to the launch (e.g. --no-sandbox)
--force	Overwrite existing AppImage, desktop entry, and icon
--skip-validation	Install/update a file even if it is not a valid AppImage (e.g. a standalone binary); icon auto-extraction is skipped
--list, -l	List installed AppImages and exit
--update TARGET	Replace an installed app's AppImage (TARGET is its slug or display name); the positional path is the new file
-h, --help	Show usage

Examples

# Basic install
./appimage-manager.sh ~/Downloads/Obsidian-1.5.3.AppImage

# Custom name and icon
./appimage-manager.sh --name "Obsidian" --icon ~/Pictures/obsidian.svg ~/Downloads/Obsidian.AppImage

# Chromium-based app that needs --no-sandbox
./appimage-manager.sh --name "Brave" --exec-args "--no-sandbox" ~/Downloads/Brave.AppImage

# Overwrite an existing install
./appimage-manager.sh --force ~/Downloads/Foo.AppImage

# List installed AppImages
./appimage-manager.sh --list

# Update an installed app with a newer AppImage (keeps its menu entry and icon)
./appimage-manager.sh --update Obsidian ~/Downloads/Obsidian-1.6.0.AppImage

# Update and replace its icon
./appimage-manager.sh --update Obsidian --icon ~/Pictures/obsidian.svg ~/Downloads/Obsidian-1.6.0.AppImage

# Install a standalone binary (not a real AppImage), e.g. Winbox
./appimage-manager.sh --skip-validation --name "Winbox" --icon ~/Pictures/winbox.png ~/Downloads/winbox

How it works

1. Copies the AppImage to ~/Applications/ and ensures it is executable.
2. Tries to extract an icon by running the AppImage with --appimage-extract and searching common icon paths; the type is determined from the filename or content (symlinked .DirIcons included), and the icon is placed in the right hicolor bucket: SVG in scalable/apps, raster in 256x256/apps. Raster icons keep the 256x256 bucket regardless of their real pixel size (desktops scale them). If no icon is found, the AppImage path is used as a fallback.
3. Writes a small launcher wrapper to ~/.local/bin/ that:
   • sets APPIMAGE_EXTRACT_AND_RUN=1 when libfuse.so.2 is missing, and
   • retries with --no-sandbox if the normal launch fails.
4. Writes a .desktop entry that references the wrapper, sets Path= to ~/Applications, passes %U so file/URL arguments work from the menu, and includes MimeType= when MIME types were provided (the TUI prefills these from the AppImage's own bundled .desktop).
5. Records the install in a registry so the TUI can list and uninstall it.
6. Refreshes the desktop caches (gtk-update-icon-cache and update-desktop-database, when available) so the entry and icon appear without re-logging in. Some desktops (e.g. Fedora) rely on the icon cache while others (e.g. Arch) pick icons up automatically; running both is harmless. The same refresh runs after updates and uninstalls.

Registry

Installed apps are tracked in:

${XDG_DATA_HOME:-$HOME/.local/share}/appimage-manager/registry.tsv

Each row stores the slug, name, AppImage path, desktop path, icon path, and wrapper path. Apps installed before the registry existed are still detected by scanning ~/Applications/*.AppImage and shown as "legacy".

Building a distributable

make bundle inlines lib/core.sh into each entrypoint, producing self-contained single files (no .sh extension, so they read as commands):

dist/appimage-manager
dist/appimage-manager-tui

To install them (~/.local/bin by default, override with PREFIX), see Installation. Bundling only, without installing, is just make bundle.

This is automated in CI (.github/workflows/): every push and pull request runs the tests and uploads dist/ as a workflow artifact, and pushing a v* tag runs the same gates, writes dist/SHA256SUMS, and publishes both bundled scripts as release assets:

git tag v1.0.0
git push origin v1.0.0

A release can be re-run without moving the tag, either from the Actions UI (Release → Run workflow) or with:

gh workflow run release.yml -f tag=v1.0.0

Re-running rebuilds the assets and updates the existing release in place.

You can find the latest built files in Releases.

Testing

make test   # shellcheck + shfmt check + build + functional tests
make lint   # shellcheck only
make fmt    # shfmt (rewrite)
make clean  # remove dist/

The test suite is headless and runs against an isolated $HOME, using stub AppImages so nothing touches your real environment.

Uninstall (manual)

Remove the installed files:

rm ~/Applications/<Name>.AppImage
rm ~/.local/share/applications/<slug>.desktop
rm ~/.local/bin/<slug>-appimage-launcher
rm ~/.local/share/icons/hicolor/256x256/apps/<slug>.png   # or .svg, if present

The TUI's Uninstall option does this automatically, including the cache refresh below. If you remove files manually, refresh the menu/caches yourself:

gtk-update-icon-cache -f -t ~/.local/share/icons/hicolor 2>/dev/null || true
update-desktop-database ~/.local/share/applications 2>/dev/null || true

Troubleshooting

• App does not appear in the menu — confirm the .desktop exists in ~/.local/share/applications/, then log out/in (or reload the shell). Verify Categories includes a recognized category (e.g. Utility;).
• Icon missing — provide one with --icon path/to/icon.svg|png; some AppImages do not ship icons in standard locations.
• Exec errors on launch — some sandboxed apps need extra flags; use --exec-args "--no-sandbox" or the TUI presets. Confirm the AppImage has execute permissions.

Sandboxing

On Ubuntu 24.04 and newer, some Electron/Chromium-based AppImages (Obsidian, Brave, etc.) fail to launch from the menu even though they run from the file manager. This is because Chromium's SUID sandbox helper is unavailable. The generated launcher tries a normal launch first and then automatically retries with --no-sandbox.

Warning: --no-sandbox disables Chromium's sandbox process isolation and reduces security. Whether that is acceptable is up to you.

Recommended: install libfuse2t64 (sudo apt install libfuse2t64) if AppImages fail to run at all, and rely on the launcher's automatic fallback.

Security notes

• Do not run untrusted AppImages.
• Writes only to user directories; no root required.
• All paths and variable expansions are quoted; the scripts use set -Eeuo pipefail and defensive checks.

License

See LICENSE.

This application was heavily inspired in AppImage-Install and released under the same license.