8

Configuration Files

Ryszard Knop edited this page 2025-04-03 18:58:56 +02:00

Table of Contents

• Profiles
• Load Order

Some itch-dl settings can be saved permanently. The main configuration file lives in:

• Windows: C:/Users/<username>/AppData/Roaming/itch-dl/config.json
• macOS: ~/Library/Application Support/itch-dl/config.json
• Linux: ~/.config/itch-dl/config.json (respects XDG_CONFIG_HOME if set)

The config.json file has the following structure (everything except the api_key is optional, make sure your file does NOT have comments):

{
    // itch.io API key - https://github.com/DragoonAethis/itch-dl/wiki/API-Keys
    "api_key": "UeqKR3nBrVCxM32qt....Ga0FH2TwwbDPIDhseFZ",

    // User agent to send with itch.io requests (defaults to "itch-dl/{version} python-requests/{version}")
    "user_agent": "Mozilla/5.0 (X11; Linux x86_64; rv:101.0) Gecko/20100101 Firefox/101.0",

    // Directory to download games to (default: the current working directory)
    "download_to": "/home/dragoon/very_safe_for_work_games",

    // Try to fetch assets (mostly screenshots) from game sites
    "mirror_web": false,

    // Just print the discovered game URLs, do not download anything
    "urls_only": false,

    // How many threads to use for simultaneous downloads (default: 1)
    // WARN: Setting this too high may impact itch.io performance. Be reasonable.
    "parallel": 1,

    // Filter downloaded files by the target platform (does not affect non-executable downloads):
    "filter_files_platform": ["windows", "linux"],

    // Filter downloaded files by their type - types defined by the uploader
    // See https://github.com/DragoonAethis/itch-dl/wiki/Upload-Types-and-Traits
    "filter_files_type": ["default", "documentation", "book"],

    // Filter downloaded files with a shell-style glob (entire file name must match, unmatched files are skipped)
    "filter_files_glob": "game_name_*_mac.dmg",

    // Filter downloaded files with a Python regex (entire file name must match, unmatched files are skipped)
    // This is a JSON string - use a double backslash to produce a single backslash in your pattern!
    // Use https://regex101.com/ -> Python flavor to test your patterns first
    "filter_files_regex": "dwarf_fortress_[\\d_]+_windows\\.zip",

    // Filter downloaded itch URLs with a shell-style glob (entire URL name must match, unmatched URLs are skipped)
    "filter_urls_glob": "https://terrycavanagh.itch.io/*",

    // Filter downloaded itch URLs with a Python regex (entire URL must match, same rules as above)
    "filter_urls_regex": "https://.*\\.itch\\.io/.*",

    // Use verbose logging by default
    "verbose": true
}

Profiles

Profiles are an easy way to switch between multiple configs - for example, if you have multiple accounts (main/developer/horny) and you'd like to easily switch the API key used for downloading a given title. By default, no profile is loaded.

• Create a profiles directory next to the config.json file.
• Create <name>.json files within that profiles directory. Their format is the same as the main config.json file.
• When running itch-dl, use the --profile <name> argument to load a specified profile.

Load Order

• The main config.json file is loaded first, if it exists.
• The profile config overrides values from the main config file, if it exists.
• Command line arguments override both of the above.