Guide

AppImage on Shani OS — Portable Apps with Gear Lever

Shrinivas Vishnu Kumbhar · 2026-05-02 · 5 min

An AppImage is a self-contained portable executable — every dependency the application needs is bundled inside a single .AppImage file. You download it, make it executable, and run it. No package manager, no installation, no modifications to the system.

On Shani OS, this is a natural fit. The OS root is read-only anyway, so AppImages — which never write to system paths — work exactly as intended. Gear Lever (pre-installed on both editions) goes further: it integrates AppImages into your application launcher, tracks updates, and stores them in a persistent bind-mount that survives OS updates and rollbacks.

Full reference: docs.shani.dev — AppImage.

---

Running an AppImage Without Gear Lever

The manual approach works for one-off tools:

# Download an AppImage (example: Obsidian)
wget https://github.com/obsidianmd/obsidian-releases/releases/download/v1.5.3/Obsidian-1.5.3.AppImage

# Make it executable
chmod +x Obsidian-1.5.3.AppImage

# Run it
./Obsidian-1.5.3.AppImage

The app runs immediately. Nothing is installed to the system. Delete the file to "uninstall."

For tools you use regularly, Gear Lever manages them properly.

---

Gear Lever — AppImage Manager

Gear Lever is pre-installed on both GNOME and KDE editions. Open it from your application launcher.

What Gear Lever Does

Desktop integration: Drag an AppImage file onto Gear Lever (or click "Add AppImage") and it adds the app to your launcher. The icon, name, and categories are read from the AppImage's embedded metadata.

Persistent storage: Gear Lever stores managed AppImages in ~/.local/share/applications/ and related paths — these are in your @home subvolume and survive all OS updates and rollbacks.

Update tracking: For AppImages that embed update information (most major projects do via zsync or GitHub releases), Gear Lever checks for and downloads updates in the background.

Version management: Keep multiple versions of the same AppImage and switch between them.

Clean removal: Remove an AppImage and its launcher entry with one click — no leftover files.

Adding an AppImage via Gear Lever

  1. Download the .AppImage file to ~/Downloads
  2. Open Gear Lever
  3. Drag the file onto the Gear Lever window, or click "+" and select the file
  4. Gear Lever reads the embedded metadata, confirms the details
  5. The app appears in your application launcher immediately

---

Where AppImages Fit in the Ecosystem

AppImages are best for apps released only in that format, for getting the absolute latest version before it reaches Flathub, or for portable tools you want to run from a USB drive. For most GUI apps, Flatpak (Flathub) is the better choice — sandboxed, auto-updating, and larger catalogue. For CLI tools, Nix. For anything needing a full distro environment, Distrobox.

The Shani OS Software Ecosystem has the full decision flowchart and comparison table.

---

AppImage Permissions

AppImages run with your user's permissions — they can access your home directory, network, and any files your user can access. Unlike Flatpak, there is no sandbox by default.

For AppImages from trusted sources (official project releases), this is generally fine. For AppImages from unknown sources, exercise the same caution you would for any downloaded executable.

Gear Lever does not add sandboxing. If you need AppImage sandboxing, run the AppImage inside a Distrobox container:

distrobox enter ubuntu-dev
./SomeApp.AppImage

---

FUSE Requirement

AppImages use FUSE (Filesystem in Userspace) to mount themselves at runtime. FUSE is pre-installed on Shani OS. If you ever see a FUSE error:

# Check FUSE is available
ls /dev/fuse

# If not present, the kernel module may need loading
sudo modprobe fuse

Some AppImages can run without FUSE by extracting themselves first:

./SomeApp.AppImage --appimage-extract
cd squashfs-root
./AppRun

---

Resources

---

Built in India 🇮🇳 · Immutable · Atomic · Zero Telemetry