Usage

Usage

Run osu-collect in a terminal. The app opens on the get maps tab with the collection field focused: paste an osu!collector link, pick a folder, activate the download button. Press ? anywhere for the key reference (Keybindings).

Sources on the get maps tab

The source row at the top switches between three ways to get maps. Cycle it with space / ↵, or jump straight to one with 1-3.

Source	What it does
collection	Downloads a whole osu!collector collection by URL or ID
find	Searches maps by criteria, no collection needed → Finding maps
update	Re-checks downloaded collections and fetches only what's missing → Updating collections

Every source shares the same download section (mirrors, directory, threads, overwrite, video); run settings persist across a source switch.

Form fields

Field	What it does
Collection URL or ID	Accepts https://osucollector.com/collections/{id} or a bare ID. Resolves as you type and remembers recent collections. Required for the collection source.
Download directory	Defaults to the last used folder. tab completes filesystem paths during editing.
Threads	Parallel downloads, defaulting to your CPU core count; 20 or fewer avoids rate limiting. Adjust with + / -.
Overwrite existing	Off (default) verifies and skips maps already on disk; on skips the recheck and redownloads every map.
Video	Includes beatmap videos (on by default); off downloads video-free where the mirror supports it.

Custom mirror URLs and the built-in mirror toggles live on the config tab → Mirrors.

Before a run starts, maps already in your osu! library (stable osu!.db or the lazer client database) are skipped instead of re-fetched; they still land in the generated collection.db. Turn this off with download.skip_already_imported (Configuration).

Every download is MD5-hashed as it streams and checked for a valid archive shape before it lands (Configuration); a bad file is deleted on the spot and the map goes to the failures list below.

Downloads tab

Every run lives on the downloads tab: active runs first, then finished ones, then past runs restored from disk. History survives restarts, cancelled runs included. A new download switches to this tab by default; turn off display.jump_to_downloads to stay where you are.

Delete a finished run or a past history entry from the list with d (an active run can't be deleted; cancel it with q first). It asks to confirm; space ticks "don't ask again" and skips the prompt from then on (re-enable via display.confirm_delete_history, Configuration).

Open a run with ↵ to see live per-map progress, download speed, ETA, rate-limit countdowns per map, plus a failure summary with reasons. Its keys are in Keybindings.

Failed maps

Failures persist per collection between runs. Three ways to retry them:

• press r inside the open run,
• accept the prompt on your next download of that collection (download.retry_failed_on_download = ask / yes / no),
• let rate-limited maps re-queue themselves after the auto-defer delay (Mirrors).