Skip to content
Linen docs

Loom's migrateMappings task

Checked against Fabric’s Migrating Mappings using Loom page on 2 November 2026.

migrateMappings is a task in Loom, Fabric’s Gradle plugin. It rewrites your Java sources from one name set to another. Fabric’s page assumes Minecraft 1.21.11 and Loom 1.13 or newer. It does not handle Kotlin; for Kotlin, Fabric points to the Ravel plugin for IntelliJ IDEA (see Yarn to Mojang names).

Main sources

Section titled “Main sources”

The version in net.minecraft:mappings:<version> must be the Minecraft version your mod is on now.

Windows:

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

macOS and Linux:

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

Then, in build.gradle, replace the Yarn mappings line with:

mappings loom.officialMojangMappings()

Refresh Gradle. Then read through your code for mixin targets and anything that was not renamed.

Client sources (split source sets)

Section titled “Client sources (split source sets)”

If your mod keeps client code in its own source set, migrate it with migrateClientMappings:

Terminal window
./gradlew migrateClientMappings --mappings "net.minecraft:mappings:1.21.11" --overrideInputsIHaveABackup

On Windows, start with ./gradlew.bat instead of ./gradlew. On older Loom versions, Fabric points you to the --input option below (--input src/client/java).

Access wideners and class tweakers

Section titled “Access wideners and class tweakers”

migrateMappings reads Java sources. Your access widener or class tweaker file has its own task:

Terminal window
./gradlew migrateClassTweakerMappings --mappings "net.minecraft:mappings:1.21.11" --overrideInputsIHaveABackup

When you later move to 26.1, also change named to official in that file’s first line (Fabric: Porting to 26.1).

Options

Section titled “Options”
Option What it sets Default
--input path/to/source Where the Java sources are read from src/main/java
--output path/to/output Where the remapped sources are written. Use src/main/java to overwrite, after a backup. remappedSrc
--mappings group:artifact:version:qualifier Which names to move to. net.minecraft:mappings:<minecraft-version> means Mojang’s names. net.fabricmc:yarn:<version>:v2
--overrideInputsIHaveABackup Used in Fabric’s main commands, which replace your current sources

Fabric’s example for migrating a client source set in place, with no separate output folder:

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

Going back to Yarn

Section titled “Going back to Yarn”

Fabric’s page also shows the reverse, from Mojang names to a Yarn build (here 1.21.11+build.3). Yarn is no longer supported by Fabric and doesn’t exist for 26.1.

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

What it won’t do for you

Section titled “What it won’t do for you”
  • It won’t touch Kotlin.
  • It won’t change build.gradle or gradle.properties.
  • Fabric says to review the result and fix things by hand, mixins most of all. See Mixins on 26.1.

In Linen

Section titled “In Linen”

Linen has no mappings-migration button yet. Run the commands above in a terminal, or ask Claude Code, Anthropic’s extension (on your own Claude plan), to run them through Linen’s gradle tool. Afterwards, hovers show each name in Mojang, Yarn, intermediary and Parchment, and Linen Check reads names, mixins and the build and names the file and the fix for what is left.