Skip to content

How to update your mod to a new Minecraft version

Update in this order. First read the loader’s migration notes for the new version (Fabric, Forge and NeoForge all publish them). Then change the Minecraft, loader and API versions in your build files, and the Java version if it changed (1.20.5 and later need Java 21, 1.18 to 1.20.4 need Java 17, 1.17 needs Java 16, and 1.16.5 and older run on Java 8). Compile. Each error is a name or a signature that changed; fix them one at a time, starting with registries and Item and Block constructors, which change most. Run the game, then fix what only shows up at runtime: data files and recipes.

Works on Minecraft 1.20.1 to 26.3 on NeoForge; Minecraft 1.16.5 to 26.3 on Fabric; Minecraft 1.16.5 to 1.20.1 on Forge; Minecraft 1.12.2 on Forge. Each example was compiled against its loader and version before it shipped in Linen.

  1. Read the migration notes for the new version from your loader.
  2. Raise the versions in gradle.properties and the mod metadata, and the Java version if needed.
  3. Compile and fix the errors from the top.
  4. Run the game and fix data files and warnings in the log.

The example mod is examplemod in the package com.example.examplemod. Use your own mod id and package.

Fabric and NeoForge 1.20.4 to 1.21.1, NeoForge 1.20.1 to 1.20.2, Fabric 1.16.5 to 1.20.3, Fabric and NeoForge 1.21.2 to 1.21.5, Forge 1.17.1 to 1.20.1

Section titled “Fabric and NeoForge 1.20.4 to 1.21.1, NeoForge 1.20.1 to 1.20.2, Fabric 1.16.5 to 1.20.3, Fabric and NeoForge 1.21.2 to 1.21.5, Forge 1.17.1 to 1.20.1”

Uses:

  • SharedConstants.getCurrentVersion
  • WorldVersion.getName

This file only reads the version. The real work of an update is in your build files and the compiler’s errors; the steps list them.

src/main/java/com/example/examplemod/VersionCheckVersion.java

package com.example.examplemod;
import net.minecraft.SharedConstants;
// Version Check: prints which Minecraft version the mod runs on. After you raise the version in your build files, a mod that
// compiles with no error here is on the new version; the errors the compiler shows next are the changes to make.
public final class VersionCheckVersion {
private VersionCheckVersion() {
}
public static String minecraft() {
return SharedConstants.getCurrentVersion().getName();
}
}

Uses:

  • SharedConstants.getCurrentVersion
  • WorldVersion.name

This file only reads the version. The real work of an update is in your build files and the compiler errors; the steps list them. Since 1.21.6 WorldVersion has name() instead of getName().

src/main/java/com/example/examplemod/VersionCheckVersion.java

package com.example.examplemod;
import net.minecraft.SharedConstants;
// Version Check: prints which Minecraft version the mod runs on. After you raise the version in your build files, a mod that
// compiles with no error here is on the new version; the errors the compiler shows next are the changes to make.
public final class VersionCheckVersion {
private VersionCheckVersion() {
}
public static String minecraft() {
return SharedConstants.getCurrentVersion().name();
}
}

Uses:

  • SharedConstants.getCurrentVersion
  • WorldVersion.getName

This file only reads the version. The real work of an update is in your build files and the compiler’s errors; the steps list them.

src/main/java/com/example/examplemod/VersionCheckVersion.java

package com.example.examplemod;
import net.minecraft.util.SharedConstants;
// Version Check: prints which Minecraft version the mod runs on. After you raise the version in your build files, a mod that
// compiles with no error here is on the new version; the errors the compiler shows next are the changes to make.
public final class VersionCheckVersion {
private VersionCheckVersion() {
}
public static String minecraft() {
return SharedConstants.getCurrentVersion().getName();
}
}

Uses:

  • SharedConstants.getCurrentVersion
  • WorldVersion.getName

src/main/java/com/example/examplemod/VersionCheckVersion.java

package com.example.examplemod;
import net.minecraftforge.fml.common.Loader;
// Version Check: prints which Minecraft version the mod runs on. After you raise the version in your build files, a mod that
// compiles with no error here is on the new version; the errors the compiler shows next are the changes to make.
public final class VersionCheckVersion {
private VersionCheckVersion() {
}
public static String minecraft() {
return Loader.MC_VERSION;
}
}

Linen’s How-tos library has this page too, with the example for your own mod’s loader and Minecraft version. Hover a name in your code and Linen points to the how-tos that explain it. Both are free. Download Linen.