---
title: "Global Settings"
description: "Configure storage paths, symlinks, desktop integration, and download behavior globally."
---

The global configuration file applies default settings to all managed apps. You can override any of these settings per app inside an [app recipe](/configuration/app-recipes).

## File location

```
~/.config/fp-appimage-updater/config.yml
```

Generate a starter file with:

```bash
fp-appimage-updater init --global
```

## Example

```yaml
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`:

```yaml
github_token: ghp_your_secret_token_here
```

<Note>
  Tokens are only sent to `api.github.com`. They are **never** shared with third-party GitHub proxies configured via `github_proxy_prefix`.
</Note>

## Fields

<ParamField path="storage_dir" type="string" default="~/.local/bin/AppImages">
  Directory where downloaded AppImage files are stored.
</ParamField>

<ParamField path="symlink_dir" type="string" default="~/.local/bin">
  Directory where symlinks to installed AppImages are created. Only used when `create_symlinks` is `true`.
</ParamField>

<ParamField path="naming_format" type="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`).
</ParamField>

<ParamField path="manage_desktop_files" type="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`.
</ParamField>

<ParamField path="create_symlinks" type="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`.
</ParamField>

<ParamField path="segmented_downloads" type="boolean" default="true">
  Splits downloads into parallel HTTP range requests when the server supports it. Speeds up large AppImage downloads on capable servers.
</ParamField>

<ParamField path="show_all" type="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.
</ParamField>

<ParamField path="respect_rate_limits" type="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.
</ParamField>

<ParamField path="github_proxy" type="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.
</ParamField>

<ParamField path="github_proxy_prefix" type="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.

  ```yaml
  # 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
  ```
</ParamField>

## 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.

<ParamField path="github_release_api_url" type="string">
  Override the GitHub REST API base URL. Useful when your apps are hosted on GitHub Enterprise Server.
</ParamField>

<ParamField path="github_release_web_url" type="string">
  Override the GitHub web base URL used to construct release page links.
</ParamField>

<ParamField path="gitlab_release_api_url" type="string">
  Override the GitLab API base URL. Set this when your apps live on a self-managed GitLab instance.
</ParamField>

<ParamField path="gitlab_release_web_url" type="string">
  Override the GitLab web base URL used to construct release page links.
</ParamField>

<Note>
  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](/configuration/app-recipes) for the full list of per-app overrides.
</Note>
