AppImage Extract Installer

A robust, per-user AppImage manager for Arch/Manjaro Linux that handles installation, extraction, and updates with a focus on idempotency and reliability.

This script lets you reliably install and manage AppImages without sudo, by extracting their contents and creating proper desktop entries that point to the extracted executables. This avoids common issues with AppImage runtimes and ensures consistent behavior across different systems.

Why Use This?

AppImages are a convenient way to distribute applications, but they can have several drawbacks:

1. Runtime Dependencies: Many AppImages rely on specific versions of FUSE (Filesystem in Userspace) which may not be installed or configured correctly on all systems. This often leads to the dreaded dlopen() or fuse errors.
2. Inconsistent Naming: Downloading different versions of the same AppImage (e.g., AppName-1.2.AppImage, AppName-1.3.AppImage) can lead to multiple, duplicate installations.
3. No Central Management: It's hard to track what AppImages are installed, where they are, and how to update them.

This script solves these problems by:

• Extracting First: Instead of running the AppImage directly, it extracts the contents. This completely bypasses the need for FUSE and avoids runtime dependency issues.
• Idempotent Installs: It uses the internal application name to identify apps, so installing a newer version will update the existing one instead of creating a duplicate.
• Robust Extraction: It uses a chain of fallback methods (including binwalk and manual offset detection) to handle even the most stubborn or oddly-packaged AppImages.
• Clean Integration: Creates standard desktop entries and icons for a seamless experience with your desktop environment (KDE, GNOME, etc.).

How It Works

The script follows a robust, multi-step process for installation:

1. Extraction Chain

It first tries to extract the AppImage using the standard --appimage-extract command. If that fails, it uses a chain of increasingly powerful fallback methods:

• unsquashfs with Offset Detection: Tries to find the SquashFS filesystem offset and extract it directly.
• binwalk Analysis: If binwalk is installed, it uses it to precisely identify the SquashFS offset for extraction.
• Manual Hexdump Analysis: If all else fails, it scans the file's hex code to find the SquashFS magic bytes and extracts from there.

2. Idempotent Naming

It determines the application's true name using this priority:

1. Internal name from the .desktop file inside the AppImage
2. --name flag provided by the user
3. The AppImage filename

3. Installation & Updates

• If the app is not already installed, it creates a directory in ~/Applications/
• If it is installed, it updates the existing installation by replacing the contents
• This means downloading Cursor-1.4.3.AppImage and later Cursor-1.5.0.AppImage will update the same "Cursor" installation

4. Desktop Integration

It creates a .desktop file in ~/.local/share/applications that points to the extracted AppRun (or other executable), and installs an icon.

File Structure

After installation, your file structure will look like:

~/Applications/cursor/                    # Application directory (based on internal name)
├── cursor.AppImage                       # Original AppImage file
├── extracted/                            # Extracted AppImage contents
│   ├── AppRun                           # Main executable
│   ├── cursor.desktop                   # Internal desktop file
│   ├── usr/                             # Application files
│   └── ...
├── icon                                 # Extracted icon file
└── .appimage-manager-meta               # Manager metadata

~/.local/share/applications/cursor.desktop  # System desktop entry
~/.local/share/icons/hicolor/256x256/apps/cursor.png  # System icon

Installation

Clone the repository and make the script executable:

git clone https://github.com/drmikecrowe/appimage-extract-installer.git
cd appimage-extract-installer
chmod +x appimage-manager.sh

Prerequisites

For basic functionality, you only need a standard Linux environment. For the enhanced extraction features, you should install:

• squashfs-tools: Provides unsquashfs for the primary fallback extraction method
• binwalk: Provides the most reliable extraction method for problematic AppImages

On Arch/Manjaro:

sudo pacman -S --noconfirm squashfs-tools binwalk

Optional utilities for better experience:

• file: For detecting SVG vs PNG icons
• rsync: For faster file copying
• xdg-utils: For menu refresh
• desktop-file-utils: For desktop integration
• kbuildsycoca5 (on KDE): For KDE menu refresh

Usage

Install or Update an AppImage

./appimage-manager.sh install /path/to/YourApp.AppImage

Optional flags:

• --name "Custom Name": Override the application name (though it's recommended to rely on the internal name for idempotency)
• --exec-args "--foo --bar": Append extra arguments to the Exec line in the .desktop file

Examples:

# Basic installation
./appimage-manager.sh install ./Cursor-1.4.3.AppImage

# Override name
./appimage-manager.sh install ./SomeApp.AppImage --name "My App"

# Add execution arguments
./appimage-manager.sh install ./Editor.AppImage --exec-args "--debug --verbose"

Uninstall an AppImage

./appimage-manager.sh uninstall "AppName"

List Installed AppImages

./appimage-manager.sh list

Get Help

./appimage-manager.sh help

Features

✅ Idempotent Installation

Installing different versions of the same app will update the existing installation rather than creating duplicates:

./appimage-manager.sh install Cursor-1.4.3.AppImage  # Installs "Cursor"
./appimage-manager.sh install Cursor-1.5.0.AppImage  # Updates "Cursor" to new version

✅ Robust Extraction

Handles problematic AppImages that fail with standard methods:

• Uses multiple fallback extraction techniques
• Works even when FUSE is unavailable or broken
• Handles corrupted or non-standard AppImage formats

✅ Clean Integration

• No sudo required - everything installs to your home directory
• Proper desktop integration with KDE and GNOME
• Automatic icon extraction and installation
• Menu refresh for immediate availability

✅ Safe Updates

• Backs up the old AppImage during updates
• Atomic updates - if something goes wrong, the old version remains functional
• Clean uninstallation removes all traces

Troubleshooting

AppImage won't extract

1. Make sure the AppImage is executable: chmod +x YourApp.AppImage
2. Install extraction tools: sudo pacman -S squashfs-tools binwalk
3. Try running the AppImage directly first to see if it's corrupted

Desktop entry doesn't appear

1. Try refreshing the menu: xdg-desktop-menu forceupdate
2. On KDE: kbuildsycoca5
3. Log out and back in
4. Check if the desktop file was created: ls ~/.local/share/applications/

App won't start from menu

1. Check if the extracted executable exists and is executable
2. Try running the extracted AppRun directly: ~/Applications/[app-name]/extracted/AppRun
3. Check the desktop file for correct paths: cat ~/.local/share/applications/[app-name].desktop

Contributing

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

Copyright 2025 Mike Crowe (drmikecrowe)