Free osu!collector downloader in your terminal
osu!collect is a terminal app (TUI) that downloads osu! beatmap collections from osu!collector. Paste a collection link, pick a folder, and it batch-downloads every map across multiple mirrors, generates a ready-to-import collection.db, and can re-check the collection later to grab only the maps you're missing.
- Batch downloads from any osu!collector collection. Paste a URL or ID, press enter.
- Mirrors with automatic failover: osu!direct, Nerinyan, Sayobot, Nekoha, Beatconnect, osu!dl, the Hinamizawa cascade, your own custom mirrors, plus the official osu! servers once you log in.
- Rate-limit aware: throttled mirrors sit out while the rest keep downloading, with per-map cooldown countdowns in the UI. Each map starts on a different mirror (round-robin) and requests to any one mirror are spaced out, so load spreads instead of hammering a single host.
- Collections updater: Re-check a collection later and download only the maps that are missing or newly added.
- Ez import with
collection.db: Maps arrive as a proper osu! collection, not a loose folder of.oszfiles. - Integrity verification: MD5 plus archive validation on every download; files already on disk are verified and skipped.
- Retry failed maps: Failures persist between runs. Retry them with one key, or on the next download.
- Parallel collection tabs: Queue several collections and download them at once.
Linux x64 / macOS Apple Silicon:
curl -fsSL https://raw.githubusercontent.com/uwuclxdy/osu-collect/main/install.sh | bashWindows x64 (PowerShell):
iwr https://raw.githubusercontent.com/uwuclxdy/osu-collect/main/install.bat -OutFile "$env:TEMP\osu-install.bat"; & "$env:TEMP\osu-install.bat"This installs to %LOCALAPPDATA%\Programs\osu-collect, adds it to your PATH, creates shortcut
on desktop and registers itself in Settings → Apps → Installed apps. No admin needed.
Download from Releases and run it in terminal.
Note
osu!collect runs in a terminal. Windows users should be able to open it with a double click as well, but it's not guaranteed. Open an Issue if it doesn't work. Windows Terminal or PowerShell 7+ are recommended.
cargo install --git https://github.com/uwuclxdy/osu-collectWindows: Settings → Apps → Installed apps → osu!collect → Uninstall.
Linux/macOS: run rm ~/.local/bin/osu-collect.
osu-collectPaste a collection link, pick a directory, press ↵.
| 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. |
| Download directory | Defaults to the last used folder. tab completes filesystem paths. |
| Threads | Parallel downloads. Defaults to your CPU core count; 20 or fewer avoids rate limiting. |
| Custom mirror URLs | Add as many as you want — each must include the {id} placeholder. A new empty row appears as you type; clearing a row removes it. Tried after the built-in mirror toggles. |
| Skip existing | Verifies and skips maps already on disk. |
| Overwrite existing | Skips the on-disk recheck and redownloads every map fresh. |
| Video | Includes beatmap videos (on by default); off downloads video-free where the mirror supports it. |
| Keys | Action |
|---|---|
| ↑ ↓ | Move between rows |
| ← → tab shift+tab | Switch tabs (tab path-completes the directory while editing it) |
| ↵ | Activate, toggle, start a download, or edit a field |
| space | Toggle the focused checkbox or switch |
| s | Jump to the download button |
| + - | Adjust thread count |
| r | Retry all failed maps on a download tab |
| x | Dismiss an error message |
| ? | Help overlay listing every key |
| q | Back / quit (press twice to confirm; aborts a running download the same way) |
| ctrl+c | Quit immediately from anywhere |
| home end | Jump to the first / last row of a list or form |
| pgup pgdn | Page a list up / down |
Text fields support full caret editing: home, end, delete, and ctrl+w to delete the previous word.
Vim keys (off by default, toggle on the config tab): h j k l move, gg / G jump to top / bottom, ctrl+u / ctrl+d page, and i / a start editing the focused field. A field in edit mode types literally; esc leaves it. When enabled, a vim marker shows in the footer.
Each queued collection gets its own tab with live per-map progress, speed and ETA, rate-limit countdowns, and a failure summary with reasons. Failed maps persist between runs. Retry them with r, or accept the prompt on your next download of that collection (configurable).
Tracks every collection you've downloaded, re-checks them against osu!collector, and shows what's missing or was removed. Pick exactly which maps to fetch, so keeping a collection current never means redownloading it.
The config tab's login chip opens a dedicated login tab where you enter your osu! username and password (masked). This signs in through osu!lazer's first-party client, which is the only way to unlock the osu! official download mirror. If osu! needs to verify a new device, the tab prompts for the emailed code. Your password is sent only to osu.ppy.sh and never stored — only the resulting token lives in auth.json (local).
Heads up: this uses osu!lazer's first-party login, an unofficial grey area. The official mirror is rate-limited (~10–20 downloads/hour) and stays off by default — keep it as a last-resort source and use it sparingly. Requests to osu! are throttled automatically (about one per second, shared across all download threads) to stay within its general API rate; the hourly download cap still applies and shows up as a temporary rate-limit when reached.
flowchart LR
A[Paste collection<br/>URL or ID] --> B[Resolve from<br/>osu!collector]
B --> C[Download across<br/>mirrors]
C --> D[Verify MD5<br/>+ archive]
D --> E[Write<br/>collection.db]
E --> F[Import<br/>into osu!]
osu! lazer
- Import all downloaded maps into lazer.
- Click
Run first time setup, thenNextuntil the Import screen. - Set
previous osu! installto the folder of the collection you downloaded. - Click
Import content from previous version. - Done. Both the maps and the collection are imported.
osu! stable
Drag the downloaded .osz files into osu!, then merge the generated collection.db with a tool like Collection Manager. If you have no existing collections, back up your own collection.db and swap in the generated one.
osu!collect reads an optional config file with defaults for mirrors, threads, archive validation, retry policy, theme, and logging:
| OS | Path |
|---|---|
| Linux / macOS | ~/.config/osu-collect/config.toml |
| Windows | %APPDATA%\osu-collect\config.toml |
Every key is documented in config.toml.example. Most settings are also editable live on the config tab, where changes apply and save immediately.
| Tool | How osu!collect differs |
|---|---|
| osu!Collector desktop client | The official app. Bulk download needs a paid subscription; osu!collect is free. |
| BatchBeatmapDownloader | Downloads by filters and criteria rather than osu!collector collections. The original inspiration for this project. |
| osu-collector-dl | A CLI script with no TUI, no collection.db generation, and no updater. |
| OsuCollectionDownloader | Generates .osdb files and needs the .NET runtime. |
| Collection Manager | Manages and merges existing collections; pairs well with osu!collect for stable imports. |
How do I download an osu!collector collection for free? Run osu!collect, paste the collection URL, press ↵. Downloads come from public beatmap mirrors, or the official servers if you log in. No subscription needed.
Does it work with osu! lazer?
Yes. See Importing into osu!. The generated collection.db imports through lazer's first-time-setup flow.
Do I need an osu! account? No. Logging in is optional and only adds the official osu! servers as an extra source.
Can it update a collection I downloaded earlier? Yes. The updates tab diffs your downloaded collections against osu!collector and fetches only what's missing.
A download failed or got rate limited. What now? Failures save per collection. Press r on the download tab to retry them all, or accept the retry prompt next time you download that collection. Rate-limited mirrors cool down on their own while the others keep going.
cargo build --releaseWindows cross-builds and requirements
Requires Rust 1.85+ (edition 2024). For Windows cross-builds, build.sh produces Linux and Windows binaries in build/.
- All features of BatchBeatmapDownloader (🚧 in the works)
Powered by osu-downloader (the bundled Rust library handling mirrors, failover, validation, and events), osu-db, and ratatui. Inspired by BatchBeatmapDownloader.
MIT. See LICENSE.