Skip to main content
Version: v1.4.0

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.4.0)

Poly Mod Loader 1.4.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, 26.3.

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:

FileUse it on
PolyModLoader-<version>.jarWindows, macOS, or Linux (requires Java 17 or later)

Install​

Double-click PolyModLoader-<version>.jar, or run it from a terminal or command prompt:

java -jar PolyModLoader-<version>.jar

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

The window opens in your system's language. The menu in its top right corner switches between English and 한국어 (Korean); what you have entered stays.

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
Fabric modLoaded on 26.1, 26.1.1, 26.1.2, 26.2, 26.3, Mixin and access wideners included. A mod that cannot run is left out with the reason in logs/latest.log. See Compatibility
NeoForge modLoaded on 26.1, 26.1.1, 26.1.2, 26.2, 26.3. Poly Mod Loader runs NeoForge itself; the first start with NeoForge mods automatically downloads NeoForge's files. A mod NeoForge would refuse is left out (POLY-COMPAT-217). See Compatibility
Forge modLoaded on 26.1, 26.1.1, 26.1.2, 26.2, 26.3. Poly Mod Loader runs Forge itself; the first start with Forge mods automatically downloads Forge's files. A mod Forge would refuse is left out (POLY-COMPAT-209). See Compatibility
Quilt modLoaded on 26.1, 26.1.1, 26.1.2, 26.2, 26.3, Mixin and access wideners included. A Quilt mod that also has fabric.mod.json runs as a Fabric mod (POLY-COMPAT-310). Mods that need Quilt Standard Libraries (QSL) are left out because QSL has no release for 26.x (POLY-COMPAT-114 with 308). See Compatibility
Mixing loadersFabric and Quilt mods run together. You can also put Fabric or Quilt mods in mods/ alongside Forge mods or alongside NeoForge mods: any Fabric or Quilt mod whose mixins do not fit that loader's patches is left out (POLY-COMPAT-224; on 26.2 three Fabric mods next to Forge (2026-10-28), 10 Fabric API modules next to NeoForge (2026-10-27)) and counted on the title screen. Forge and NeoForge mods cannot be in mods/ together yet (POLY-COMPAT-221). On Minecraft 26.3, mixing loaders works since 1.2.5 (in 1.2.4 the game stopped at start). See Run Fabric and Forge mods together
Poly Mod (a jar with poly.mod.json)Loaded

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 Fabric or Quilt mods were left out because Poly Mod Loader cannot run them next to that loader yet, one more line says how many: Not loaded, Poly Mod Loader can't run them yet: N. That is a limitation of Poly Mod Loader, not a bug in those mods: please report it on GitHub Issues to Poly Mod Loader, not to the mods' authors.

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
Title screen shows Not loaded, Poly Mod Loader can't run them yet: N (POLY-COMPAT-224)A Fabric or Quilt mod in mods/ has mixins that do not fit Forge's or NeoForge's patches yet (or depends on a Fabric API module that was left out). Check logs/latest.log for POLY-COMPAT-224 and POLY-COMPAT-114 to see which mods were skipped. See Run Fabric and Forge mods together
NeoForge mods are skipped when Forge mods are in mods/ (POLY-COMPAT-221)Forge and NeoForge cannot run in the same game yet. Keep either Forge mods or NeoForge mods in mods/, not both
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