Get started
Running in three minutes
If you just want one check to complete, do these five things. Each step ends with “What you will see” — that is what it looks like when the step worked. If it does not appear, jump to “When something goes wrong”.
Step 1
Find your mods folder
A server's mods folder usually sits in the server root, at a path like C:\servers\survival\mods.
You do not need to copy it anywhere, and you do not need to stop the server first. The folder stays read-only the whole way through.
C:\servers\survival\
|-- mods\ # this one
| |-- fabric-api-0.92.2.jar
| `-- sodium-0.6.5.jar
|-- server.jar
`-- server.propertiesWhat you will see: a folder full of .jar files. The tool reads their file names and the metadata inside each jar — it never modifies, moves, deletes or adds a single file.
Step 2
Build a profile
Desktop app: menu “Profiles → Scan a mods folder…”, then pick the folder from step 1.
Command line: start it and press 2 in the main menu.
A profile is modcheck's word for one record of which mods a server has installed. Build it once; every later check reuses it.
What you will see: a progress bar sweep the folder, then “identifying online”, and after a moment a count of the mods it recognised. This step takes every jar to Modrinth and CurseForge once — the more mods you have, the longer it takes, and that is normal.
Step 3
Name the profile and save it
The name is yours to choose, “survival” for example. It only tells your servers or modpacks apart, and it does not affect the verdicts.
What you will see: a confirmation that the profile was saved, plus how many mods it holds. The profile lives in the config folder next to the program.
Step 4
Run a check
Pick the profile (survival) → pick the target version (26.3, say) → pick the loader (Fabric most of the time) → start the check.
What you will see: progress move mod by mod, and a verdict banner at the end telling you how the profile looks as a whole. A first check over 120–200 mods usually takes 1–3 minutes.
Step 5
Read the verdict and act
The results are split across tabs by state. Click a row and the panel below shows the detail for that mod, with a recommendation.
| State | Meaning | What you should do |
|---|---|---|
| Ready | A usable version exists for the target version | Nothing to do |
| Check | The latest release does not support it, but an earlier stable build does | Use that older stable build, not the newest one |
| Beta only | Only alpha/beta supports the target version | Judge the risk yourself; back up your world first |
| Blocked | No usable version at all for the target version | Must be solved first, or you cannot upgrade |
| Undetermined | Nothing found — not a failure | Re-run later; name the platform project by hand if needed |
| Ignored | You marked it as out of scope | Not part of the verdict |
What you will see: the word “Unknown” is nowhere in the list. When it cannot find an answer it says Undetermined — it will not quietly pick a version for you.
When something goes wrong
These are the ones people hit most often. Open the one that matches.
Online identification is slow — has it hung?
No. Identification queries Modrinth and CurseForge once per mod, so the first run always looks like this. Thirty mods means thirty lookups, and a poor connection makes it worse.
Let it finish. Closing the window halfway wastes the run — whatever was already looked up stays in the cache, but that identification never completes.
Some mods show Undetermined — is that an error?
No. Undetermined only means the platforms had nothing on file for that mod. It does not mean the mod is incompatible, and it is not a failure.
Three causes cover most cases: the mod is published only on CurseForge, or only on the author's own site; the name inside the jar does not match the project name on the platform; or the platform simply has not indexed it yet.
Re-run later first. If it stays Undetermined, name the platform project by hand — better that than letting it guess.
How: in the desktop app, open the menu Profile → Manage profiles…, select the mod in the list on the right, then click "Set platform project" at the bottom and pick the right project from the search results. In the command line edition, choose [3] Manage profiles from the main menu, open the profile, then [3] Set platform project (manual match) and enter the mod's index or name.
It remembers your choice, so later checks will not ask again.
The single-file build flashes and vanishes
The single-file build unpacks itself into the system temp directory before it runs. Antivirus software sometimes blocks that, and the symptom is exactly a window that flashes and disappears.
Switch to the standalone folder build (modcheck-<version>-cli-standalone.zip). Nothing gets unpacked to temp, it is far less likely to be blocked, and it starts faster too.
Where does the config live, and how do I move machines?
In the config folder next to the program. It is portable by design: no registry keys, no writes outside its own folder.
Copy the whole program folder to the new machine and the profiles and settings come with it. No need to rescan the mods folder.
Why is the second check so much faster?
Because it hits the cache. Version data fetched on the previous run is stored locally, so a repeat lookup for the same mod reads from disk instead of the network. Modrinth data is cached for 6 hours by default.
To force a fresh round of queries, pass --refresh, or clear the cache.
The desktop build does nothing when I double-click it
First check that you extracted it before running it, rather than double-clicking inside an archive preview. The desktop build needs the Qt libraries and the Python runtime next to it; dragging the exe out on its own will not start.
If it is already extracted, try 启动GUI.cmd in the same folder. If that fails too, run the CLI for the same check — its errors are far more direct.
I do not know which loader to pick
Look at the script or jar your server starts from: a name containing fabric means Fabric, neoforge means NeoForge, forge means Forge.
If the server has no loader installed at all, there are no mods to check either.
Command reference
Everything the desktop app does, the CLI does too — they run the same verdict code.
Interactive: run 启动CLI.cmd and pick a number from the text menu; building a profile is 2.
Scripted:
# Scan a mods folder and build a profile
modcheck scan "C:\servers\survival\mods" --profile survival
# Run one check
modcheck check --profile survival --mc 26.3 --loader fabric
# Also export JSON and Markdown reports
modcheck check --profile survival --mc 26.3 --loader fabric --json report.json --md report.md
# Ignore the cache and re-query everything
modcheck check --profile survival --mc 26.3 --loader fabric --refreshCommon arguments
| Argument | What it does |
|---|---|
--profile <name> | Which profile to use |
--mc <version> | The target Minecraft version, 26.3 for example |
--loader <loader> | Fabric, NeoForge or Forge |
--mods-dir <dir> | Point straight at a mods folder and skip the profile |
--json <file> | Also write the results as JSON |
--md <file> | Also write a Markdown report |
--refresh | Ignore the cache and re-query everything |
--jobs <n> | How many queries to run at once |
--quiet | Show a count for the Ready group instead of every row |
--pre | Count beta and alpha as usable |
--yes | Non-interactive: always take the default |
--no-color | Turn off coloured output — for logs and CI |
Exit codes
| Code | When you get it |
|---|---|
0 | Every mod is Ready, or the only findings are Check and Beta only |
1 | At least one mod is Blocked |
2 | At least one mod is Undetermined, and nothing is Blocked |
3 | Bad arguments or a broken config |
4 | The data source is down as a whole (cannot reach Modrinth) |
130 | Interrupted (Ctrl+C) |
When several conditions apply, only one code comes back. The priority is 3 > 4 > 130 > 1 > 2 > 0.
Glossary
A handful of words show up again and again. Here they are.
- Loader
- The server framework that makes mods run: Fabric, NeoForge or Forge. The same mod is usually published separately per loader, which is why a check has to be told which one you run.
- Profile
- One record of which mods a server has installed. Build it once and every later check reuses it.
- Release
- A stable Minecraft version published by Mojang, 26.3 for example. Verdicts target releases by default.
- Snapshot
- A preview build between two releases. modcheck does not check snapshot versions.
- alpha / beta
- Test builds published by a mod author. When only those support the target version, the state is Beta only.
- Undetermined
- Nothing usable was found. That is neither a failure nor “incompatible”. Re-run, or name the platform project by hand.
Next
One run is done. The next one is the server you were actually planning to upgrade.