Mod Migrator

Mod Migrator

If a Fabric 1.21.1 client mod that can answer a question: if I move my mod to another Minecraft version or another mod loader — which ones would support it?

Why this exists

Moving a modded setup to a new Minecraft version, or across loaders (Fabric → Forge / NeoForge), normally means checking every installed mod by hand: does it have a build for the target version? Does it exist on that loader at all? What replaces the ones that don't? And which new required dependencies will the target builds pull in? With a large mods folder that is an evening of browser tabs — and launchers don't help, because their update features work within an instance's own version, never across versions or loaders.

Mod Migrator turns all of that into one in-game screen: scan what you have, pick a target, and get a grouped report — what migrates, what needs which dependencies, and exactly why the rest can't — then download everything that transfers in one go.

Features

• One-screen migration report. Two panes: your installed mods on the left (with their real icons), results on the right grouped into Migratable, Required dependencies and Cannot migrate, each with a count, Modrinth / CurseForge source badges, and a click-the-header select-all.
• Dual-platform search. Modrinth by SHA-1 hash (no account or key needed), CurseForge by file fingerprint (MurmurHash2) using your own free API key. Requests are batched — a whole search costs about two Modrinth calls — and follow Modrinth's User-Agent and rate-limit rules.
• Cross-loader alternatives. When a mod has no build on the target loader, a curated equivalence table suggests the known counterpart — Sodium → Embeddium, Iris → Oculus, Lithium → Canary/Radium — shown renamed as the alternative with a "replaces X" subtitle. One line per entry in Equivalents.java, easy to extend.
• Dependency awareness. Required dependencies of the found target builds are resolved (one level, on both platforms), listed in their own section, labeled "needed by X", downloadable alongside — and flagged in red if the target version of a required dependency doesn't exist.
• Built-in downloader. Tick rows, hit Download, and a native OS dialog asks where to save: either into an auto-created folder (default mods) or a single zip archive. Per-file progress, filename-collision handling. CurseForge files whose authors disabled API downloads get a ↗ link to the mod page instead.
• Honest failure reasons. "No build for this version/loader", "not indexed on either platform", and network failures split into DNS failure, connection refused (firewall), timeout, TLS interception, bot-protection block, and rate limiting (with the wait time).
• Bilingual UI. Follows the game language: Simplified and Traditional Chinese included, everything else falls back to English.
• Client-side and lightweight. No server component, no telemetry, no bundled API keys.

Quick start

1. Requirements: Minecraft 1.21.1 with Fabric Loader ≥ 0.19.3
2. Drop the jar into mods, launch, click Mod Migrator on the title screen.
3. Left pane: tick the mods to check. Enter the target version, pick the loader (Fabric / Forge / NeoForge), press Search.
4. Review the right pane, tick what you want, choose Folder or Zip, press Download.
5. Drop the produced files into the mods folder of your new instance.

CurseForge API key (optional, recommended)

Modrinth works out of the box. To also search and download from CurseForge:

1. Get a free API key at https://console.curseforge.com/.
2. After the first launch, open config/modmigrator.properties and set curseforge-api-key=YOUR_KEY.
3. No restart needed — the key is re-read on every search.

Keep the key private: don't share the config file, and don't embed keys in jars you distribute (it violates CurseForge's terms).

What it deliberately does not do

• It prepares files and a report; it does not create instances or install loaders.
• Dependencies are resolved one level deep.
• OptiFine can't be suggested or downloaded automatically — it isn't distributed through the Modrinth or CurseForge APIs.
• Remote icons aren't fetched (Modrinth serves many WebP icons, which Minecraft can't decode); alternatives and dependencies get letter avatars instead.