This is the install and self-update helper for the itch.io app
https://itchio.itch.io/itch-setup
It applies a few tricks it learned from Squirrel.Mac and Squirrel.Windows, and uses some of the same technology behind butler, itch.io's command line uploader and patcher.
Something like this:
This is a screen you should only see the first time you launch the itch.io app, or if your itch install gets corrupted on disk somehow.
Any upgrades happen seamlessly in the background.
itch-setup is responsible for installing, updating, and launching the itch.io desktop app. It handles:
- First-time installation with a graphical progress indicator
- Background updates while the app is running
- Relaunching after updates are applied
- Uninstallation
| Flag | Description |
|---|---|
--prefer-launch |
Try to launch an existing installation first; only run setup if no valid version is found |
--upgrade |
Check for and apply updates (used by the running app for background updates) |
--relaunch |
Wait for a process to exit, then relaunch the app (used after applying updates) |
--relaunch-pid <pid> |
PID to wait for before relaunching (required with --relaunch) |
--uninstall |
Remove the installation |
--appname <name> |
Specify which app to manage: itch or kitch |
--silent |
Run installation without showing the GUI |
--info |
Display installation information and exit |
- Fetch latest version - Query the Broth package server for the latest version number
- Download signature - Fetch the archive signature file for verification
- Stream and extract - Download the archive while extracting files, using wharf's "healing" mechanism
- Stage in temp folder - New installs go to a staging directory first
- Swap atomically - Move the staged version to the final location, renaming any existing version to
.old - Create shortcuts - Set up desktop shortcuts, start menu entries, or
.desktopfiles (platform-specific) - Launch the app - Start the newly installed itch app
For updates, the same process is used but the new version is queued as "ready" and applied on the next relaunch.
| Platform | Base Directory | App Location |
|---|---|---|
| Windows | %LOCALAPPDATA%\itch\ |
%LOCALAPPDATA%\itch\app-<version>\ |
| Linux | ~/.itch/ |
~/.itch/app-<version>/ |
| macOS | ~/Library/Application Support/itch-setup/ |
~/Applications/itch.app |
Each installation directory contains:
state.json- Tracks current and ready versionsapp-<version>/- The installed app files (or staging directory during install)staging/- Temporary directory used during installation
itch-setup uses a "multiverse" system to manage versions, tracked in state.json:
{
"current": "25.6.2",
"ready": ""
}- current - The version that's installed and actively used
- ready - A version that's been downloaded but not yet activated (pending relaunch)
When an update is downloaded, it's stored as "ready". On the next relaunch (via --relaunch), the ready version becomes current.
Broth is itch.io's package distribution service. itch-setup fetches packages from Broth at URLs like:
https://broth.itch.zone/itch/linux-amd64/LATEST
https://broth.itch.zone/itch/linux-amd64/<version>/archive/default
itch-setup is MIT-licensed, see LICENSE for details