Skip to main content
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

Generate a starter file with:

​
Example

​
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:
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.

​
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