Yarn: a community named mapping for Minecraft, built one pull request at a time

A naming project with a public domain licence

Yarn is a set of open, unencumbered Minecraft mappings, free for everyone to use under the Creative Commons Zero licence. The stated intention is to let everyone mod Minecraft freely and openly, while also being able to innovate and process the mappings as they see fit.

That last clause is the part that matters for anyone who has worked with mappings before. Mappings are not just a dictionary, they are a licence negotiation. The names in a mapping set are derived from the obfuscated symbols in the game jar, and the symbol names themselves, and any human naming derived from them, carry whatever terms the source of those names imposed. That is why MCP, Spigot's mappings and Mojang's own obfuscation maps are not simply public domain, and why every mapping project has to think about it.

Yarn's answer is to have a community write the names from scratch, under a licence that can be CC0. The rule in the contributing section is not subtle: copying and pasting mappings from projects under more restrictive licences such as MCP, Spigot's or Mojang's obfuscation maps is completely forbidden without explicit permission from those owners, and this includes using the names from those mappings for inspiration. Even discussing the naming approaches used in those projects is not welcome.

The result is a mapping set that anyone can use, redistribute, rename, feed into their own tooling, or build a commercial product on, with no attribution obligation and no copyleft. For a modding ecosystem, that is a structural decision rather than a detail.

One narrow exception is documented. Some icons in Filament, which Yarn uses to develop itself, are licensed under Apache-2.0 and live in filament/src/main/resources/icons, and they are not shipped with Yarn.

The branch name is the Minecraft version

There is no version field to read and no manifest to inspect. To see the current version being targeted, check the branch name.

That is the whole versioning model, and it is elegant in the way that avoids a whole class of problem. The default branch here is 1.21.11, which is the Minecraft version the mappings on that branch describe. When a new Minecraft release lands, the work is a new branch, and the previous branch remains as the stable reference for mods that have not migrated.

This matters for anyone consuming the mappings. A mod that targets one Minecraft version pins its Yarn branch, and a mod that supports several versions either ships several variants or relies on the toolchain to map between them. There is no single artifact to download, because the artifact is a set of names that corresponds to a specific game version.

The repository structure supports that model. The top level holds a mappings/ directory, the filament/ tooling used to develop Yarn, src/, a build.gradle, gradle.properties, settings.gradle, an enigma_profile.json, an annotations.json, an unpick-definitions/ directory with unpick-logging.properties, and both CONVENTIONS.md and CONTRIBUTING.md.

The annotations.json and unpick definitions are the least visible and most interesting parts of the tree.

Using Yarn in a mod project, through fabric-loom

Consuming Yarn is not a step you perform directly. To use yarn-deobfuscated Minecraft for modding or as a dependency in a Java project, you use the loom Gradle plugin, and the project points at the fabric wiki tutorial for the setup steps.

That division is deliberate and worth understanding before you go looking for a jar to download. Yarn produces names. Loom consumes those names and applies them, which is why the setup lives in the Gradle build rather than in a file you download.

The intermediary layer is the part that makes the whole thing work, and it appears in Yarn's own documentation in a way that explains the design. The build task produces a tiny mapping between three naming schemes: official, which is the obfuscated names, intermediary, and yarn names, which it calls named. The mapNamedJar task builds a deobfuscated jar with the Yarn mappings applied and with fields automapped, enums and so on, and any name that has not been mapped gets filled in with intermediary names.

So there are three vocabularies in play. Official is what the game ships. Intermediary is a stable, machine generated middle layer that does not change with human naming decisions. Yarn is the human layer, the one people read.

That is why you can hand a modder a Yarn named jar and they get readable code, and why a build machine can still work with something stable. It is also why a mapping project can rename freely without breaking the machine layer underneath.

The Gradle tasks, and what each one actually produces

Yarn uses Gradle to provide a set of utility tasks for working with the mappings, and the task list is short enough to read in full.

The yarn task sets up, downloads and launches the latest version of Enigma, the user interface for editing the mappings, already configured to use the merged jar and the mappings. Compared with launching Enigma externally, the task adds a name guesser plugin that automatically maps enums and a few constant field names. The yarnCommon task is the same but shows only common classes.

The build task produces a GZip'd archive containing a tiny mapping between the official, intermediary and named names, and packages the Enigma mappings into a zip archive.

The mapNamedJar task builds a deobfuscated jar with the Yarn mappings and automapped fields, filling unmapped names with intermediary names. The decompileCFR task decompiles the mapped source code, with the note that this is not designed to be recompiled, which is a caution about the decompiler output rather than about the mappings.

The download task downloads the client and server Minecraft jars for the current Minecraft version to .gradle/minecraft, and mergeJars merges the client and server jars into one merged jar located at VERSION-merged.jar in the mappings directory, where VERSION is the current Minecraft version. The formatMappings task formats and sorts the mappings so they are in a consistent order.

Two details in that list are worth flagging. The merge step exists because the client and server are separate artifacts that have to be combined before you can name the code, and the format step exists because the mappings are a shared file that a hundred contributors edit, which means it has to be normalised before it can be merged without noise.

Contributing a name, which is the actual workflow

The getting started steps for a contributor are four, and they say a lot about how the project is run.

First, fork and clone the repo. Second, run the Gradle task that launches Enigma.

./gradlew yarn

On Windows the command is the same without the leading path separator, `gradlew yarn`, and the task opens Enigma, the user interface for editing mappings.

Third, commit and push your work to your fork. Fourth, open a pull request with your changes.

The build script requires Java 17 or higher, which is stated plainly because it is the single most common reason a new contributor cannot get started.

What makes this workflow notable is that the unit of contribution is a name, and names are subjective. The project handles that with a written standard. The contributing guide asks you to look at the naming conventions before submitting mappings, and the CONVENTIONS.md file at the repository root is that standard.

It also has an unusual social rule, stated firmly. Discussing the naming approaches used in the restricted-licence projects is not welcome, and there is a warning attached. But consulting about name changes with other people is encouraged, through pull requests or the community spaces. So the model is: strict isolation of the source material, open discussion of the work itself.

The repository's topics list hacktoberfest alongside fabric, minecraft and modding, which tells you the community is used to a steady flow of small contributions, the kind of workload that a naming project can absorb.

What Yarn is not, and the alternative worth considering

The comparison that matters is not with other mapping projects, because the licensing rules make them not comparable. It is with not mapping at all, or with a commercial tool.

The realistic alternatives are three. The first is to write a mod against intermediary names, which are stable and machine generated but not human readable, and which change when the game changes. The second is to use a mapping set from a project with a more restrictive licence, which is what the community was doing before, and which is what the strict no-copying rule in the contributing guide exists to prevent. The third is a commercial or closed mapping service, where the names come with terms attached.

The difference in approach is that Yarn treats the naming as a community research project with a written convention and a review process, and then donates the result to the public domain. Everything else follows from that. Because the names are unencumbered, other projects can consume them, transform them, or ignore them. Because the intermediary layer sits between official and named, a change to the human names does not break the machine layer.

The limitation follows from the same place. Naming is slow. A new Minecraft version arrives with a large set of new classes, and each one has to be named by someone, reviewed, and merged, and the branch for that version is not usable as a named reference until enough of it is done. That is a rate limit imposed by human attention, and it is the reason a mod that wants readable names immediately has to wait.

If you need names today for a brand new Minecraft version, no community mapping project can promise that. If you need names that are free to use, redistributable and free of attribution, Yarn is the clearest answer in the ecosystem.

Editorial conclusion

Yarn fits anyone writing a Minecraft mod who wants readable class and method names without licensing questions, and it fits teams that need the same names as the rest of the modding community so that patches and documentation transfer between projects. It does not fit a modder who wants a single binary that handles mapping, remapping and deobfuscation for them, since Yarn ships names and expects you to run the tooling, and it does not fit a project that needs the mappings to track a Minecraft version faster than the community can name it. Check three things before you commit. Check the branch you depend on, because the current version being targeted is the branch name, with the default branch here at 1.21.11, so there is no version field in a manifest to read. Check where the naming decisions come from, because the project explicitly forbids copying names from mapping projects under more restrictive licences such as MCP, Spigot's or Mojang's, and even using them for inspiration is out of bounds, which is the legal reason the CC0 licence is achievable at all. And check the Java version, because running the Yarn build script requires Java 17 or higher. The last push was on 2026-05-27, there are no GitHub releases, and the licence is CC0, which places the mappings in the public domain with no attribution requirement.

Frequently asked questions

Official sources

1. FabricMC/yarn on GitHub
2. Issues
3. License: CC0-1.0
4. README