How to Set Up a Fabric Dev Environment

Setting up a Fabric modding environment takes four steps: install a Java Development Kit, start from the official example mod template, configure Yarn mappings, then run Gradle. The Fabric build plugin downloads Minecraft and wires up everything else. Match your JDK and Minecraft version up front and the build system handles the rest.

What you need first

Before you write code:

• A JDK matching your Minecraft version. Newer Minecraft releases need newer JDKs. Check your target version's requirements before installing.
• An IDE. IntelliJ IDEA Community (free) or Eclipse both work well. Most Fabric developers use IntelliJ because Gradle integration is smoother.
• Git. You'll clone the template repository and manage your own code.

You do NOT need to install Gradle. The template includes a wrapper script that downloads the correct version on first run.

Step by step

1. Install a JDK

   Download a JDK from Adoptium or Oracle matching your target Minecraft version. For Minecraft 1.21, install Java 21. Point your IDE at this JDK in its settings.

2. Get the example mod template

   Go to the official Fabric GitHub example mod repository and clone it or use it as a template. Rename the package and mod ID to your own.

3. Set versions in gradle.properties

   Open gradle.properties and update three lines:

   • minecraft_version — your target Minecraft version (e.g., 1.21)
   • loader_version — the Fabric loader version matching your Minecraft build
   • yarn_mappings — the Yarn version for your Minecraft release

   These three MUST match or the project won't build.

4. Open in your IDE and sync

   Open the project folder in your IDE. Let Gradle perform an initial sync (downloads dependencies, generates run configurations).

5. Generate decompiled sources

   In your IDE's Gradle panel, run genSources. This decompiles Minecraft using Yarn names so you can read the game's code.

6. Launch a test client

   Run runClient to start Minecraft with your mod loaded. The development client includes full debugging capabilities.

That's it. You now have a working Fabric development environment.

Understanding gradle.properties

This file configures your entire build. Three versions must stay in sync:

minecraft_version=1.21
loader_version=0.15.11
yarn_mappings=1.21+build.32

If Minecraft is 1.21 but Yarn is 1.20.1, Gradle sync fails with a cryptic error. Always fetch matching versions from fabricmc.net/use or the example template.

What the build plugin does

The Fabric Gradle plugin is configured in build.gradle and handles:

• Downloading Minecraft
• Decompiling with your chosen mappings
• Remapping your code back to intermediary for compatibility
• Generating IDE run configurations

You configure it once; it automates the rest. This is why the template matters—it already has all this wired up correctly.

Mappings explained

Minecraft ships obfuscated (class names like a, b, c). Mappings translate these to readable names.

• Yarn: Fabric's default. Includes documentation. Easy to read.
• Mojang Mappings: Official but less documented. More obscure names.

The template uses Yarn. When you run genSources, Minecraft gets decompiled using Yarn names so you can read actual code. When you compile, Fabric remaps it back to intermediary (a stable layer underneath) so the mod works on any matching Minecraft version.

Common setup problems

• ✓Gradle sync fails immediately: check gradle.properties. Minecraft, loader, and Yarn versions must match. Use a known combination from the Fabric website.
• ✓Compiler error about Java version: your JDK is too old for the Minecraft version. Install a newer JDK and point your IDE at it.
• ✓Can't read Minecraft source code: run genSources in the Gradle panel and reload. The first run is slow because it decompiles the whole game.
• ✓runClient does nothing: wait for the initial Gradle sync to complete. Run configurations are generated during sync.
• ✓IDE won't import the project: make sure the IDE has a JDK selected in its settings, not a JRE.

Next steps after setup

Once your environment works:

1. Delete or rename the example mod classes
2. Create your own mod package
3. Implement a simple feature (a block, item, or event listener)
4. Run runClient and test in the development client
5. Iterate

The development client includes full debugging and hot-reload support, making iteration fast.

IDE-specific notes

IntelliJ IDEA:

• Import as Gradle project (not just a folder)
• Let Gradle sync fully before running any task
• Run configurations appear under "Gradle" in the run dropdown

Eclipse:

• Import as an existing Gradle project
• Right-click project → Gradle → Refresh Gradle Project after sync
• Gradle tasks appear in the Gradle Tasks view

FAQ