INFO

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.

Historically, Minecraft: Java Edition has made use of obfuscation, which led to the development of obfuscation maps that Fabric Loom uses for modding. There were two choices: either Fabric's own Yarn mappings, or the official Mojang mappings.

Mojang have recently announced they're removing code obfuscation from Minecraft: Java Edition, and the Fabric Project followed up with its plan for handling this change.

You may wish to migrate from Yarn to Mojang Mappings, especially if you are planning on updating your mod past the Mounts of Mayhem game drop. To do this, or to switch to Yarn from another mapping set, Loom offers a semi-automated migration of the mappings through the migrateMappings task.

Loom does not support migrating code written in Kotlin.

What Are Mappings?

Minecraft: Java Edition has been obfuscated since its release, which means that its code had human-friendly class names like Creeper replaced with gibberish like brc. In order to easily mod it, Fabric Loom makes use of obfuscation maps: references which translate obfuscated class names, such as brc, back to human-friendly names like CreeperEntity.

As a Fabric developer, you'll encounter three main sets of names:

• Intermediary: The mapping set used by compiled Fabric mods; for example brc may become class_1548. The point behind Intermediary is offering a stable set of names across releases, as obfuscated class names change with each new version of Minecraft. This often allows mods built for one version to work on others, as long as the affected parts of the game haven't changed too much.
• Yarn: an open-source mapping set developed by Fabric for humans to write mods. Most Fabric mods used Yarn Mappings, as they were the default before 2025. An example mapping might be CreeperEntity.
• Mojang Mappings: The game's official obfuscation mappings, released by Mojang in 2019 to aid mod development. Notably, Mojang's obfuscation mappings lack parameter names and Javadocs, which is why some users also layer Parchment over the official mappings. An example mapping might be Creeper.

The game drop following Mounts of Mayhem will be deobfuscated and include parameter names, so there won't be a need for any obfuscation mappings. If you are updating your mod to this version, you will need to move to Mojang's obfuscation mappings first before updating.

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.10:

Windows

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

macOS/Linux

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

IntelliJ

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

You can replace 1.21.10 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.10" --overrideInputsIHaveABackup

macOS/Linux

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

IntelliJ

migrateMappings --mappings "net.minecraft:mappings:1.21.10" --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

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.10+build.2"

macOS/Linux

./gradlew migrateMappings --mappings "1.21.10+build.2"

IntelliJ

migrateMappings --mappings "1.21.10+build.2"

You can replace 1.21.10 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.10+build.2 --overrideInputsIHaveABackup"

macOS/Linux

./gradlew migrateMappings --mappings "1.21.10+build.2 --overrideInputsIHaveABackup"

IntelliJ

migrateMappings --mappings "1.21.10+build.2 --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.10+build.2

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.10"

macOS/Linux

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

IntelliJ

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

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.10"

macOS/Linux

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

IntelliJ

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

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.10"

macOS/Linux

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

IntelliJ

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