Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.fau.fpt.icu/llms.txt

Use this file to discover all available pages before exploring further.

The global configuration file applies default settings to all managed apps. You can override any of these settings per app inside an app recipe.

​
File location

~/.config/fp-appimage-updater/config.yml
Generate a starter file with: 
fp-appimage-updater init --global

​
Example

storage_dir: ~/.local/bin/AppImages
symlink_dir: ~/.local/bin
naming_format: '{name}.AppImage'
manage_desktop_files: true
create_symlinks: false
segmented_downloads: true
show_all: false
respect_rate_limits: true
github_proxy: true
github_proxy_prefix: https://gh-proxy.com/

​
GitHub Rate Limits & Tokens

GitHub imposes rate limits on its REST API for unauthenticated requests (60 requests per hour per IP). To bypass this, you can provide a personal access token (PAT), which increases your limit to 5,000 requests per hour.

​
Configuration methods

fp-appimage-updater checks for a token in the following order:
  1. Environment Variable: Set the GITHUB_TOKEN environment variable in your shell or service manager.
  2. Secrets File: Create a secrets.yml file in your config directory. This is the recommended method for dotfile users who want to keep secrets separate from general configuration for easier encryption.
  3. Global Config: You can also place github_token directly in config.yml, though this is discouraged for security reasons.

​
Using secrets.yml

Create the file at ~/.config/fp-appimage-updater/secrets.yml: 
github_token: ghp_your_secret_token_here
Tokens are only sent to api.github.com. They are never shared with third-party GitHub proxies configured via github_proxy_prefix.

​
Fields

​
storage_dir
string
default:"~/.local/bin/AppImages"
Directory where downloaded AppImage files are stored.
​
symlink_dir
string
default:"~/.local/bin"
Directory where symlinks to installed AppImages are created. Only used when create_symlinks is true.
​
naming_format
string
default:"{name}.AppImage"
Filename template for stored AppImages. Supported placeholders:
  • {name}: Replaced with the app’s name field from its recipe.
  • {version}: Replaced with the resolved version of the app (e.g., 1.2.3).
​
manage_desktop_files
boolean
default:"true"
When enabled, fp-appimage-updater automatically extracts .desktop manifests and icons from the AppImage and installs them into ~/.local/share/applications and ~/.local/share/icons.
​
create_symlinks
boolean
default:"false"
When enabled, creates a symlink in symlink_dir pointing to the installed AppImage. Useful for putting AppImages on your PATH without modifying storage_dir.
​
segmented_downloads
boolean
default:"true"
Splits downloads into parallel HTTP range requests when the server supports it. Speeds up large AppImage downloads on capable servers.
​
show_all
boolean
default:"false"
When enabled, update includes apps that are already up to date in its output. By default, only apps that were updated, rate-limited, or failed are shown.
​
respect_rate_limits
boolean
default:"true"
When enabled, apps that hit a provider rate limit are skipped on subsequent runs until the retry window expires. Set to false to always attempt the request regardless of a prior rate limit.
​
github_proxy
boolean
default:"true"
Enables the GitHub API proxy fallback. When a GitHub release API request is rate limited, fp-appimage-updater retries through the configured proxy bases. The actual AppImage download always uses the direct GitHub asset URL — only metadata lookups are proxied.
​
github_proxy_prefix
string | string[]
default:"all"
Proxy base URL(s) to use when github_proxy is enabled. Accepts a single URL string, a YAML list of URLs, or the string all to try every built-in proxy in order.
# Single proxy
github_proxy_prefix: "https://gh-proxy.com/"

# Multiple proxies tried in order
github_proxy_prefix:
  - "https://gh-proxy.com/"
  - "https://corsproxy.io/?"
  - "https://api.allorigins.win/raw?url="

# Try all built-in proxies
github_proxy_prefix: all

​
Self-hosted forge URL overrides

These optional fields let you point fp-appimage-updater at a self-hosted GitHub or GitLab instance instead of the public APIs.
​
github_release_api_url
string
Override the GitHub REST API base URL. Useful when your apps are hosted on GitHub Enterprise Server.
​
github_release_web_url
string
Override the GitHub web base URL used to construct release page links.
​
gitlab_release_api_url
string
Override the GitLab API base URL. Set this when your apps live on a self-managed GitLab instance.
​
gitlab_release_web_url
string
Override the GitLab web base URL used to construct release page links.
Every field in config.yml can be overridden for a specific app inside its recipe file. App-level settings always take precedence over the global config. See app recipes for the full list of per-app overrides.
Last modified on April 24, 2026