Port a mod between Minecraft versions
Porting a mod means building it against another Minecraft version and fixing what no longer compiles or loads. Work in this order: save the mod, put the old and new versions side by side, update the build files, let the right Java install, fix the compile errors, fix the data files and mixins, then run the game.
Linen does not rewrite your code for a new version by itself. Mod Updater shows what breaks when you move a mod to a newer Minecraft version, and Claude Code in Linen’s panel can help with the port (see With Claude Code). What Linen has is listed under each step. Checked against Linen 0.2.1 on 20 November 2026.
Moving to 26.1 or newer? That port has its own rules, because 26.1 dropped obfuscation. Read Port a mod to 26.1 first.
Step 1: Save what works
Section titled “Step 1: Save what works”Commit the mod, or press Save a version in Linen. Some steps below change many files, and you want a way back.
Step 2: Put the versions side by side
Section titled “Step 2: Put the versions side by side”Keep the old version buildable while you work on the new one. There are three common layouts, and Linen opens all of them:
| Layout | What it is | In Linen |
|---|---|---|
| A folder per version | 1.20.1/, 1.21.1/ and so on, each a full project |
Open the parent folder with Open. Linen sets each version up, and the version switcher in the status bar moves between them in one window |
| A branch per version | One project, one Git branch for each Minecraft version | Open the folder as usual and switch branches in the Git view or a terminal |
| Stonecutter | One source tree in src/, with a node for each version and loader in versions/ |
Open the folder. Linen reads the Stonecutter build and makes one target per node, with the active node first. Play the game asks which target to run |
To start a second version from scratch, New mod can make the same mod for several Minecraft versions at once. It writes a folder per version.
What Linen does not do with Stonecutter yet: it does not switch the active version for you, Use Stonecutter’s own Gradle tasks for its //? version comments.
Step 3: Update the build files
Section titled “Step 3: Update the build files”The Gradle plugin, the Gradle wrapper, the loader version and the Java version all depend on the Minecraft version. The fastest way to get them right is to compare with a project that already builds:
- Make a throwaway project with New mod for the same loader and the new Minecraft version.
- Compare its
build.gradle,gradle.properties,settings.gradleandgradle/wrapper/gradle-wrapper.propertieswith yours, and copy the version numbers across. - Swap every dependency for a build made for the new version.
The numbers Linen’s templates use for each version are in Set up a Fabric mod, Set up a NeoForge mod and Set up a Forge mod.
Step 4: Get the right Java
Section titled “Step 4: Get the right Java”Each Minecraft version runs on one Java version: 8 up to 1.16.5, 16 for 1.17, 17 from 1.18 to 1.20.4, 21 from 1.20.5 to 1.21.11 and 25 from 26.1. Gradle itself may need a newer one. Which Java version has the table and the sources.
Linen installs the Java a project needs when you open it. If the build still fails, Getting started on Home shows the Java this mod needs and warns when JAVA_HOME points at
another one. See Wrong Java version.
Step 5: Fix the compile errors
Section titled “Step 5: Fix the compile errors”Build the mod. Linen’s Problems view lists the Java errors, each linked to its line. Then, for each error:
- A class or method is gone or renamed. Search for it in Find anything (Ctrl+P). It lists the names of Minecraft and the loader for the version you have open. Hover the old name in the old version’s folder to see what it did, and look for its replacement in the new one.
- You are not sure how the new version does it. Open Minecraft’s own code for the new version and use Find usages to see how the game calls the method.
- The whole approach changed, as items did with data components in 1.20.5. The how-to library shows the steps for your loader and version, where a how-to covers them. Most how-tos are for 1.21.1, and some also have 1.20.1 or 26.3 versions.
The loaders publish porting notes for each version. Read them before you guess: Fabric’s are on its blog, NeoForge’s on its news page.
Step 6: Fix data files and mixins
Section titled “Step 6: Fix data files and mixins”- Data folders. Minecraft 1.21 renamed several data folders to the singular:
loot_tablesbecameloot_table, andrecipesbecamerecipe. Linen Check reads loot tables, recipes, models and names the way the game will and names the file to change. - Mixins. A target method that was renamed or changed its parameters makes the mixin fail at start-up. Linen Check reads your mixins the way the game will. See Fix common mixin and crash errors.
- Access wideners and transformers. Entries name the game’s classes and members, so renamed ones stop matching. See Access widener or class tweaker and Access transformer not applied.
Step 7: Run it
Section titled “Step 7: Run it”Press Play the game and test what your mod adds. If the game crashes, Crash Doctor (free) reads the report and names the mod and the line. Then check the new version with Linen Check before you publish it. A release check that runs Linen Check and every Replay in one pass is planned.
With Claude Code
Section titled “With Claude Code”If you use Claude Code on your own Claude plan, /port <version> in Linen’s panel starts a port, and /fix hands it the
errors Linen shows now. Claude knows the mod’s loader and version, can check which versions have a method and can read
Minecraft’s code from your own jar, all free. It can still be wrong, so build and play after each part. Ask it for the list
of renamed and removed classes first, as in Make a Minecraft mod with AI.
How Linen uses AI says what is sent where.
What is planned
Section titled “What is planned”A Mod Updater that also retargets mixins and runs the game and your Replays on the new version is planned. It is not in Linen today.