Skip to main content
Version: Minecraft 26.2

Install Poly Mod Loader (players)

The installer adds a Poly Mod Loader <Minecraft version> profile (for example Poly Mod Loader 26.2) to the official Minecraft Launcher. Play with that profile and the game starts through Poly Mod Loader.

Stable release (1.0.0)

Poly Mod Loader 1.0.0 is a stable release. Back up worlds you care about before you add new mods. Supported Minecraft versions: 26.1, 26.1.1, 26.1.2, 26.2.

Before you start​

  1. In the Minecraft Launcher, run vanilla Minecraft once in the version you want (for example 26.2), then quit. This downloads the game files and the launcher's Java.
  2. Close the Minecraft Launcher. If you install while the launcher is open, the launcher may delete the new profile when it exits.

Download​

The download page lists every Poly Mod Loader build, with a short summary of what changed. The files come from GitHub releases. Each build has two files:

FileUse it on
PolyModLoader-<version>.exeWindows. You do not need to install Java separately (it uses the Java the launcher downloaded)
PolyModLoader-<version>.jarmacOS, Linux, or Windows with Java 17 or later installed
Windows "PC protection" warning

The installer is not code-signed yet, so Windows SmartScreen may warn you the first time you run it. If you downloaded the file directly from the GitHub release, click More info → Run anyway.

Install​

Run PolyModLoader-<version>.exe.

In the window, pick the Minecraft version, check the launcher folder, and click Install.

The default launcher folder is %APPDATA%\.minecraft on Windows, ~/Library/Application Support/minecraft on macOS, and ~/.minecraft on Linux.

Memory. Choose how much memory the game may use:

  • Maximum memory (-Xmx): the installer suggests a size from your PC's memory (4G with 8 GB, 6G with 16 GB or more). Launcher default keeps the launcher's own setting (2G).
  • Starting memory (-Xms): usually leave it at Not set.

The sizes go into the profile's JVM arguments in the launcher, so you can change them there later. Other JVM arguments you set there are kept.

When it's done, a notification tells you whether the install worked. Click it to open the mods folder. The installer then closes by itself. Untick Close the installer when done to keep it open. It also stays open when there is a warning to read.

What the installer does:

  • Puts the Poly Mod Loader files in the launcher folder's libraries/.
  • Creates the version versions/polymodloader-<version>-<Minecraft version>/. It uses the vanilla game files unchanged and starts them through Poly Mod Loader.
  • Adds a Poly Mod Loader <Minecraft version> profile to launcher_profiles.json. Other profiles are left alone. The file as it was before the change is kept as launcher_profiles.json.polymodloader-backup.
  • Creates the mods/ folder.

Installing again repairs the profile or moves it to the new Poly Mod Loader version. Installing for another Minecraft version adds a second profile.

Play​

  1. Open the Minecraft Launcher.
  2. In the list next to the play button, choose Poly Mod Loader <Minecraft version> and play.
  3. Put mods in the launcher folder's mods/.
Jar in mods/How it is handled
Poly Mod (a jar with poly.mod.json)Loaded
Fabric modLoaded, Mixin included. A mod that cannot run is left out, with the reason in the log. On the client, popular Fabric mods play a saved world together, save it and quit (138 on 26.2, 126 on 26.1). Features were not checked mod by mod. See Compatibility
Forge modLoaded. Poly Mod Loader runs Forge itself; the first start with Forge mods downloads Forge's files. A mod Forge would refuse is left out, with the reason in the log (POLY-COMPAT-209). On the client, popular Forge mods play a saved world together, save it and quit (40 on 26.2), also next to Fabric mods. Features were not checked mod by mod. See Run Fabric and Forge mods together
Quilt modLoaded on 26.1, 26.1.2 and 26.2, Mixin and access wideners included, also next to Fabric and Forge mods. A mod that needs Quilt Standard Libraries (QSL) is left out, because QSL has no release for 26.x (POLY-COMPAT-114 with 308). On the client, the Quilt-only builds on Modrinth for each version play a saved world together, save it and quit (155 mods on 26.2, 88 of them Quilt mods). Features were not checked mod by mod. A Quilt mod that also has fabric.mod.json runs as a Fabric mod (310). See Compatibility
NeoForge modLoaded on 26.1, 26.1.2 and 26.2. Poly Mod Loader runs NeoForge itself; the first start with NeoForge mods downloads NeoForge's files. A mod NeoForge would refuse is left out, with the reason in the log (POLY-COMPAT-217). On the client, popular NeoForge mods play a saved world together, save it and quit (54 on 26.2, Sodium and Iris among them). NeoForge mods do not run in the same game as Fabric or Quilt mods yet: then the NeoForge mods are left out, with the reason in the log (POLY-COMPAT-216). With Forge mods, Forge runs and the NeoForge mods are left out. Features were not checked mod by mod. See Compatibility

The title screen shows how many mods each loader loaded, in the bottom-left corner above the game version (for example Poly mods: 2 and Fabric mods: 14), in the game's language. A loader with no mods has no line. With Forge or NeoForge mods, these lines go above the lines that loader shows.

If a mod is also on a server you join, use the same mod version on both sides.

Install from the command line​

The .jar also works without a window.

java -jar PolyModLoader-<version>.jar install                          # install into the default launcher folder
java -jar PolyModLoader-<version>.jar install --minecraft <Minecraft version>  # pick the Minecraft version (default: the newest)
java -jar PolyModLoader-<version>.jar install --dir <launcher folder>  # another folder (if you moved the launcher install location)
java -jar PolyModLoader-<version>.jar install --no-profile             # install the version only, do not create a profile
java -jar PolyModLoader-<version>.jar install --max-memory 6G --min-memory 1G  # the game's memory (-Xmx, -Xms)
java -jar PolyModLoader-<version>.jar uninstall                        # uninstall
java -jar PolyModLoader-<version>.jar --help

Uninstall​

Click Uninstall in the installer, or run uninstall. It removes the Poly Mod Loader version, the profile, and the Poly Mod Loader files. It leaves the mods/ folder and your worlds alone.

If something goes wrong​

SymptomWhat to do
The launcher has no Poly Mod Loader profileClose the launcher and install again. If you changed the launcher folder, choose that folder in the installer
The .exe says it could not find JavaRun vanilla Minecraft once from the launcher and try again, or run the .jar with Java 17 or later
The game quits right after startingFind an error code that starts with POLY- in logs/latest.log in the launcher folder and look it up in Error codes. If a mod caused it, remove it from mods/ and run again
POLY-BOOTSTRAP-006Install again with the installer
POLY-COMPAT-133 in the logA Fabric mod's Mixin failed on a game class. The message names the mod. Remove that mod or look for a newer version

Poly Mod Loader writes a startup report to .poly/startup-report.json in the launcher folder. Attach it when you report a problem.

Dedicated server​

The same installer sets up a server. A server needs Java 25 or newer.

  1. Open the installer, choose Server, and pick a server folder.
  2. Pick the Minecraft version and the server's memory, and click Install.

The installer downloads Mojang's server for that version and checks it. It then puts the Poly Mod Loader files next to it and creates these files:

  • run.bat (Windows) and run.sh start the server with the memory you chose.
  • polymodloader-server.jar starts it on any host: java -Xmx4G -jar polymodloader-server.jar nogui.

The first start stops at Minecraft's EULA. Read the EULA, set eula=true in eula.txt, and start again. The installer never accepts it for you.

Put mods in the server folder's mods/. Installing again into the same folder updates Poly Mod Loader and keeps your worlds, settings and mods.

On a server without a desktop, use the command line:

java -jar PolyModLoader-<version>.jar install-server                     # into this folder
java -jar PolyModLoader-<version>.jar install-server --dir <server folder> --minecraft <Minecraft version> --max-memory 4G
Buy me a coffee