Quick Start Tutorial - fp-appimage-updater

This guide walks you through setting up fp-appimage-updater from scratch: initializing your global config, writing an app recipe, and installing your first AppImage.

Initialize the global config

Run the init --global command to create the default global configuration file:

fp-appimage-updater init --global

This creates ~/.config/fp-appimage-updater/config.yml with sensible defaults for storage paths, desktop integration, segmented downloads, and more. Open the file to review or adjust the settings before continuing.

Create your first app recipe

Use init --app to scaffold a recipe file for an app. Pass --strategy to choose the update strategy. This example uses the forge strategy for a GitHub-hosted app:

fp-appimage-updater init --app hydra-launcher --strategy forge

This creates ~/.config/fp-appimage-updater/apps/hydra-launcher.yml. Edit it to match your target repository and asset filename pattern:

name: hydra-launcher
strategy:
  strategy: forge
  repository: https://github.com/hydralauncher/hydra
  asset_match: "hydralauncher-*.AppImage"

The asset_match field is a wildcard pattern matched against release asset filenames. Adjust it to select the correct AppImage for your architecture.

Validate the recipe

Before fetching anything, confirm the recipe parses correctly:

fp-appimage-updater validate hydra-launcher

If the file has any syntax errors or missing required fields, the command reports them so you can fix them before running an update.

Check for updates

Query the upstream release to see whether a new version is available:

fp-appimage-updater check hydra-launcher

The command reads your local state first, then asks the upstream source for metadata, and compares the two. The output shows the resolved version, whether a download is needed, and any support hints such as range download availability.

Install or update the app

Download and install the AppImage (and its desktop integration if enabled):

fp-appimage-updater update hydra-launcher

The command follows the same check-first flow, then downloads the new AppImage only if needed. It prefers the built-in zsync-rs delta path when you have a local AppImage and the recipe enables it, falls back to segmented HTTP or a normal download, then marks the file executable, updates the symlink if enabled, rewrites the desktop entry and icon if enabled, and finally saves the new state.

For real-world recipe examples for popular apps like Obsidian, CurseForge, and Sioyek, check the official examples folder on GitLab.

To explore all available recipe fields and strategy options — including direct (ETag/Last-Modified) and script (custom resolver) — see the Update Strategies page.

Documentation Index