WARNING

For best results, it's recommended to update to Loom 1.13 or above, as it allows for migrating Mixins, Access Wideners and client source sets.

Migrating to Mojang Mappings

First, you need to run a migrateMappings command that will migrate your current mappings to Mojang Mappings. For example, the following command would migrate to Mojang Mappings for 1.21.11:

Windows

./gradlew.bat migrateMappings --mappings "net.minecraft:mappings:1.21.11"

macOS/Linux

./gradlew migrateMappings --mappings "net.minecraft:mappings:1.21.11"

IntelliJ

migrateMappings --mappings "net.minecraft:mappings:1.21.11"

You can replace 1.21.11 with the version of Minecraft you are migrating from. This must be the same version of Minecraft you are currently running. Do not modify your gradle.properties or build.gradle yet!

Editing Your Sources

By default, the migrated source code will appear in remappedSrc, rather than overwriting your existing project. You'll need to copy the sources from remappedSrc to the original folder. Make sure to back up the original sources, just in case.

If you are using Loom 1.13 or above, you can use the program argument --overrideInputsIHaveABackup to replace your sources directly.

Windows

./gradlew.bat migrateMappings --mappings "net.minecraft:mappings:1.21.11" --overrideInputsIHaveABackup

macOS/Linux

./gradlew migrateMappings --mappings "net.minecraft:mappings:1.21.11" --overrideInputsIHaveABackup

IntelliJ

migrateMappings --mappings "net.minecraft:mappings:1.21.11" --overrideInputsIHaveABackup

Updating Gradle

If you are coming from Yarn, you can now replace your mappings in your build.gradle's dependencies section with Mojang Mappings.

dependencies {
    [...]
    mappings "net.fabricmc:yarn:${project.yarn_mappings}:v2"
    mappings loom.officialMojangMappings() 
}

You can now refresh the Gradle project in your IDE to apply your changes.

Final Changes

That's the bulk of the work done! You'll now want to go through your source code to check for any potentially outdated Mixin targets or code that was not remapped.

Tools like mappings.dev or Linkie will be helpful to familiarize yourself with your new mappings.

Migrating to Yarn

WARNING

1.21.11 is the final release where Yarn Mappings will be available. If you plan to update your mod to 26.1 or above, your mod should be on Mojang's Mappings.

First, you need to run a migrateMappings command that will convert your current mappings to Yarn Mappings. This can be found on the Develop site under Mappings Migration. For example:

Windows

./gradlew.bat migrateMappings --mappings "1.21.11+build.3"

macOS/Linux

./gradlew migrateMappings --mappings "1.21.11+build.3"

IntelliJ

migrateMappings --mappings "1.21.11+build.3"

You can replace 1.21.11 with the version of Minecraft you are migrating from. This must be the same version of Minecraft you are currently running. Do not modify your gradle.properties or build.gradle yet!

Editing Your Sources

By default, the migrated source code will appear in remappedSrc, rather than overwriting your existing project. You'll need to copy the sources from remappedSrc to the original folder. Make sure to back up the original sources, just in case.

If you are using Loom 1.13 or above, you can use the program argument --overrideInputsIHaveABackup to replace your sources directly.

Windows

./gradlew.bat migrateMappings --mappings "1.21.11+build.3" --overrideInputsIHaveABackup

macOS/Linux

./gradlew migrateMappings --mappings "1.21.11+build.3" --overrideInputsIHaveABackup

IntelliJ

migrateMappings --mappings "1.21.11+build.3" --overrideInputsIHaveABackup

Updating Gradle

If you are migrating from Mojang Mappings, you can now replace your mappings in your build.gradle's dependencies section with Yarn Mappings. Make sure to also update your gradle.properties file with the Yarn version specified on the Develop site.

gradle.properties

yarn_mappings=1.21.11+build.3

build.gradle

dependencies {
    [...]
    mappings loom.officialMojangMappings() 
    mappings "net.fabricmc:yarn:${project.yarn_mappings}:v2"
}

You can now refresh the Gradle project in your IDE to apply your changes.

Final Changes

That's the bulk of the work done! You'll now want to go through your source code to check for any potentially outdated Mixin targets or code that was not remapped.

Tools like mappings.dev or Linkie will be helpful to familiarize yourself with your new mappings.

Additional Configurations

Migrating Split Sources

Loom 1.13 adds a new migrateClientMappings task that can be used to migrate your client sourceset to your new mappings. For example, to migrate to Mojang Mappings:

Windows

./gradlew.bat migrateClientMappings --mappings "net.minecraft:mappings:1.21.11"

macOS/Linux

./gradlew migrateClientMappings --mappings "net.minecraft:mappings:1.21.11"

IntelliJ

migrateClientMappings --mappings "net.minecraft:mappings:1.21.11"

If you are using an older version of Loom, see other configurations.

Migrating Access Wideners

Loom 1.13 adds a new migrateClassTweakerMappings task that can be used to migrate your access wideners to your new mappings. For example, to migrate to Mojang Mappings:

Windows

./gradlew.bat migrateClassTweakerMappings --mappings "net.minecraft:mappings:1.21.11"

macOS/Linux

./gradlew migrateClassTweakerMappings --mappings "net.minecraft:mappings:1.21.11"

IntelliJ

migrateClassTweakerMappings --mappings "net.minecraft:mappings:1.21.11"

Other Configurations

• Specify where to take your Java source files from with --input path/to/source. Default: src/main/java. You can use this to migrate a client sourceset by passing --input src/client/java.
• Specify where to output the remapped source with --output path/to/output. Default: remappedSrc. You can use src/main/java here to overwrite existing sources, but make sure you have a backup.
• Specify a custom place to retrieve the mappings from with --mappings some_group:some_artifact:some_version:some_qualifier. Default: net.fabricmc:yarn:<version-you-inputted>:v2. Use net.minecraft:mappings:<minecraft-version> to migrate to official Mojang mappings.

For example, to migrate a client source set to Mojang Mappings in-place (overwriting the existing sources):

Windows

./gradlew.bat migrateMappings --input "src/client/java" --output "src/client/java" --mappings "net.minecraft:mappings:1.21.11"

macOS/Linux

./gradlew migrateMappings --input "src/client/java" --output "src/client/java" --mappings "net.minecraft:mappings:1.21.11"

IntelliJ

migrateMappings --input "src/client/java" --output "src/client/java" --mappings "net.minecraft:mappings:1.21.11"