ntegrating an AppImage into the Ubuntu Menu

appimage-integration-guide.md

Integrating an AppImage into the Ubuntu Menu

A repeatable, no-extra-tools method for making any .AppImage behave like an installed app — searchable in Activities, pinnable to the dock, with a proper icon. Tested on Ubuntu 24.04.

Throughout, replace APPNAME with a short lowercase name for the app (e.g. freecad, arduino-ide, qgroundcontrol) and agtbaskara with your username if different.

---

The pattern at a glance

1. Put the AppImage in ~/Applications/ with a clean, version-less name.
2. Make it executable.
3. Extract it once to pull out the icon and read its bundled .desktop file.
4. Copy the icon out.
5. Write your own .desktop file using the bundled metadata, but with absolute paths.
6. Delete the extracted folder and refresh the menu.

Once done, updating is trivial: delete the old AppImage, drop in the new one, rename it to the same name. The .desktop file never needs touching.

---

Step 1 — Place and name the file

Keep all AppImages in one permanent folder so you don't lose them:

mkdir -p ~/Applications
mv ~/Downloads/APPNAME*.AppImage ~/Applications/APPNAME.AppImage

Use a clean lowercase name with no version number (arduino-ide.AppImage, not arduino-ide_2.3.10_Linux_64bit.AppImage). This is what makes future updates a simple file-swap.

Step 2 — Make it executable

chmod +x ~/Applications/APPNAME.AppImage

Without this, the menu entry will silently do nothing.

Step 3 — Extract and inspect

Don't guess where the icon is — extract once and look:

cd ~/Applications
./APPNAME.AppImage --appimage-extract

This creates a squashfs-root/ folder. Find the icon and read the app's own desktop entry:

# find bundled icons (png or svg)
find squashfs-root -maxdepth 3 \( -name "*.png" -o -name "*.svg" \) | head

# show the bundled .desktop file
cat squashfs-root/*.desktop 2>/dev/null

The bundled .desktop is gold — copy its Categories, Keywords, StartupWMClass, and note any special Exec flags (see the notes section).

Step 4 — Copy the icon out

Pick whichever the app provides (.svg is best — scales cleanly):

cp ~/Applications/squashfs-root/<ICON_FILE> ~/Applications/APPNAME.svg
# or .png if that's what it ships

Step 5 — Write your .desktop file

User-level entries live in ~/.local/share/applications/. Template:

cat > ~/.local/share/applications/APPNAME.desktop << 'EOF'
[Desktop Entry]
Type=Application
Name=Display Name Here
Comment=Short description
Exec=/home/agtbaskara/Applications/APPNAME.AppImage
Icon=/home/agtbaskara/Applications/APPNAME.svg
Terminal=false
Categories=Utility;
Keywords=keyword1;keyword2;
StartupWMClass=WMClassFromBundledFile
EOF

Fill in Name, Comment, Categories, Keywords, and StartupWMClass from the bundled file you read in Step 3.

Step 6 — Clean up and register

rm -rf ~/Applications/squashfs-root
update-desktop-database ~/.local/share/applications/

Search the app's name in Activities — it should appear within seconds. If not, log out and back in.

---

Important notes

Use absolute paths

The Exec and Icon lines must be full paths (/home/agtbaskara/...). The ~ shortcut does not reliably expand in a .desktop file, and the bundled file's own values (Exec=AppRun, Icon=APPNAME) only work inside the AppImage's runtime — not from your menu.

Preserve special Exec flags

Whatever the bundled .desktop had after the executable, keep it. Common ones:

Flag / arg	Why it matters
--no-sandbox	Electron apps (e.g. Arduino IDE) often won't launch without it
--single-instance	Stops a new process launching each time (e.g. FreeCAD)
%U / %F	Lets the app open files/URLs you double-click on
a lone -	App-specific separator (FreeCAD uses this) — keep its position

Example preserving flags: Exec=/home/agtbaskara/Applications/arduino-ide.AppImage --no-sandbox %U

Validate the file (optional)

desktop-file-validate ~/.local/share/applications/APPNAME.desktop

No output means it's well-formed.

---

Updating an app later

Because the filename has no version in it:

rm ~/Applications/APPNAME.AppImage
mv ~/Downloads/APPNAME-new-version*.AppImage ~/Applications/APPNAME.AppImage
chmod +x ~/Applications/APPNAME.AppImage

Done. No need to touch the .desktop file or re-extract the icon.

Removing an app

rm ~/Applications/APPNAME.AppImage
rm ~/Applications/APPNAME.svg          # or .png
rm ~/.local/share/applications/APPNAME.desktop
update-desktop-database ~/.local/share/applications/

---

Hardware access (serial devices)

Apps that talk to microcontrollers or flight controllers over USB serial (Arduino IDE, QGroundControl, etc.) need your user in the dialout group:

sudo usermod -aG dialout $USER

Log out and back in for it to take effect. If a ModemManager service grabs the port, you may also need to remove it:

sudo apt remove modemmanager

---

Common pitfalls

• Menu entry does nothing → forgot chmod +x, or a typo in the Exec path.
• Generic/broken icon → Icon= path is wrong, or the icon file was deleted.
• App won't start (Electron) → missing --no-sandbox.
• Older AppImages fail with libfuse.so.2 error → sudo apt install libfuse2.
• Entry doesn't appear → run update-desktop-database, then log out/in.