Skip to content

How to make a Minecraft mod in 2026

To make a Minecraft: Java Edition mod, you write Java code for a mod loader (Fabric, NeoForge or Forge), build it with Gradle and test it in a development copy of the game. Pick one loader and one Minecraft version, and install the JDK that version needs (Java 21 for 1.20.5 – 1.21.11, Java 25 for 26.1 and newer). Start from the loader’s template, run ./gradlew runClient, and build the jar with ./gradlew build.

Last checked on 3 November 2026. ./gradlew build and ./gradlew runClient were run on a Fabric 1.21.1 and a NeoForge 1.21.1 project made from Linen’s templates. The code shown comes from those projects. It is template code, plus the block properties in step 6, which were added by hand and built.

What Why Where
A 64-bit JDK (Java Development Kit) of the version your Minecraft version needs Gradle compiles your mod with it Which Java version; Temurin builds at adoptium.net
An editor or IDE that understands Gradle projects Code completion, the game’s names, run configurations IntelliJ IDEA (Fabric’s docs recommend it, with the Minecraft Development plugin), Eclipse (NeoForge’s docs support it), or Linen
The loader’s template The Gradle build, the metadata file and a main class Fabric’s template generator, NeoForge’s MDK, Forge’s MDK
Some Java Mods are Java classes Any Java course or book

You don’t need to install Gradle. Every template has a Gradle wrapper (gradlew and gradlew.bat) that downloads the Gradle version the project asks for.

Pick the loader your players or your modpack already use. If you have no preference:

  • Fabric has the most mods on Modrinth for 1.21.11 and every 26.x version, and the second most on 1.21.1.
  • NeoForge has the most mods on Modrinth for 1.21.1.
  • Forge has the most mods for 1.20.1 and the older long-lived versions: 1.19.2, 1.18.2, 1.16.5 and 1.12.2.

The numbers, the history and the trade-offs are in Fabric vs NeoForge vs Forge. If you want to change a server without players installing anything, write a plugin instead. See How to make a Paper plugin.

Step 2: Which Minecraft version should you mod?

Section titled “Step 2: Which Minecraft version should you mod?”

Mod the version you want to play or the version your modpack uses. A mod is built against one Minecraft version, and its metadata says which versions it accepts ("minecraft": "~1.21.1" in the Fabric test project), so the choice matters.

Version Why people pick it
1.20.1 The most mods on Modrinth: 35,047 mod projects list it. Forge’s largest version
1.21.1 Second, with 32,673 mod projects. The largest version for both Fabric and NeoForge
26.x The current game. 26.1 was the first version without obfuscation, so mods use Mojang’s own names (Fabric, 14 March 2026)

Counts from Modrinth’s search API on 3 November 2026, across 21 release versions from 1.12.2 to 26.3. A project counts for a version if any of its files lists that version.

This guide uses 1.21.1. On other versions the steps are the same, though the Java version and some folder names change.

Install the JDK your Minecraft version runs on. Mojang’s version files name it (javaVersion in each version’s JSON):

Minecraft Java
1.12.2 – 1.16.5 8
1.17 – 1.17.1 16
1.18 – 1.20.4 17
1.20.5 – 1.21.11 21
26.1 and newer 25

Fabric’s docs say the same for 1.21.1: “To develop mods for Minecraft 1.21.1, you will need JDK 21.” NeoForge’s Getting Started asks for “the Java 21 Development Kit (JDK) and 64-bit Java Virtual Machine (JVM).”

Gradle itself may need a newer Java than your mod. Linen’s Fabric 1.21.1 template compiles the mod for Java 21 but runs Gradle on Java 25, because the Fabric Loom version it uses refuses older Javas. Installing both 21 and 25 fixes this. The details are in Which Java version.

Use the loader’s own starting point:

  • Fabric: fill in fabricmc.net/develop/template (mod name, package name, Minecraft version) and download the zip. Fabric’s docs ask you to avoid cloud-synced folders, spaces and non-ASCII characters in the project path.
  • NeoForge: start from the MDK repository linked from Getting Started with NeoForge, with “Use this template” on GitHub or as a zip.
  • Forge: download the MDK from files.minecraftforge.net and extract it into an empty folder (Forge docs).
  • IntelliJ IDEA: the Minecraft Development plugin adds a Minecraft project type to New Project (Minecraft Dev docs).

Open the folder in your IDE and let it import the Gradle project. The first import downloads Minecraft, the loader and the libraries. NeoForge’s docs warn that this first load can take up to an hour, so give it time.

A Fabric 1.21.1 project from Linen’s template, with the mod id guidemod:

guide-fabric/
├── build.gradle the build: Loom, Minecraft, Fabric Loader, Fabric API
├── gradle.properties the versions: minecraft_version=1.21.1, loader_version, fabric_api_version
├── settings.gradle where Gradle finds the Fabric plugin
├── gradlew, gradlew.bat the Gradle wrapper
└── src/main/
├── java/net/example/guidemod/
│ ├── GuideMod.java the main class (the entrypoint)
│ └── registry/ ModBlocks, ModItems, ModCreativeTabs
└── resources/
├── fabric.mod.json the mod's id, name, entrypoint and dependencies
├── assets/guidemod/ blockstates, models, textures, lang (client side)
└── data/guidemod/ loot tables, recipes (game data)

A NeoForge project has the same src/main/java, assets and data folders. Its metadata is META-INF/neoforge.mods.toml (in this template under src/main/templates/, filled in from gradle.properties at build time) instead of fabric.mod.json.

Use lowercase letters, digits and underscores, start with a letter, and keep it between 2 and 64 characters. That fits both Fabric’s rule (^[a-z][a-z0-9-_]{1,63}$, which also allows hyphens) and NeoForge’s (lowercase letters, digits and underscores, 2 to 64 characters). The mod id becomes the namespace of everything you add, as in guidemod:ruby_block, so changing it later means renaming files.

The loader calls your main class when the game starts. On Fabric it implements ModInitializer, and fabric.mod.json names it under entrypoints.main:

public class GuideMod implements ModInitializer {
public static final String MOD_ID = "guidemod";
public static final Logger LOGGER = LoggerFactory.getLogger(MOD_ID);
@Override
public void onInitialize() {
ModBlocks.register();
ModItems.register();
ModCreativeTabs.register();
}
public static ResourceLocation id(String path) {
return ResourceLocation.fromNamespaceAndPath(MOD_ID, path);
}
}

On NeoForge it has the @Mod annotation, and its constructor gets the mod’s event bus:

@Mod(GuideMod.MOD_ID)
public class GuideMod {
public static final String MOD_ID = "guidemod";
public GuideMod(IEventBus modEventBus, ModContainer modContainer) {
ModBlocks.BLOCKS.register(modEventBus);
ModItems.ITEMS.register(modEventBus);
modEventBus.addListener(ModCreativeTabs::addToVanillaTabs);
}
}

A block is one field in Java plus a few resource files. On Fabric 1.21.1, in ModBlocks:

public static final Block RUBY_BLOCK = register("ruby_block",
new Block(BlockBehaviour.Properties.of()
.mapColor(MapColor.COLOR_RED)
.strength(5.0F, 6.0F)
.sound(SoundType.METAL)
.requiresCorrectToolForDrops()));

It also needs a block item, a blockstate, a block model, an item model, a 16 × 16 texture, a loot table, an English name and, for requiresCorrectToolForDrops(), a mining tag. Each file, its path and what breaks without it is in How to add a block in Fabric and NeoForge 1.21.1.

Step 7: How do you run the game with your mod?

Section titled “Step 7: How do you run the game with your mod?”
Terminal window
./gradlew runClient

On Windows, use gradlew.bat runClient or .\gradlew runClient. The task starts a development copy of Minecraft with your mod loaded. Fabric’s and NeoForge’s docs list the same task, and IDEs show it as a run configuration.

On the Fabric 1.21.1 test project, the game log showed:

[main/INFO] (FabricLoader/GameProvider) Loading Minecraft 1.21.1 with Fabric Loader 0.20.1
[main/INFO] (FabricLoader) Loading 56 mods:
- guidemod 1.0.0

The 56 are Fabric API’s modules, Fabric Loader, MixinExtras, Minecraft, Java (21, the version the game ran on) and your mod. The template puts the ruby block in the Building Blocks tab of the creative inventory.

./gradlew runServer starts a test server instead. The first start stops right away. Accept the Minecraft EULA in eula.txt in the run folder, and set online-mode=false in server.properties so the test player can join (NeoForge docs).

Terminal window
./gradlew build

The jar lands in build/libs/. The Fabric test project made guidemod-1.0.0.jar and guidemod-1.0.0-sources.jar. Fabric’s docs say to use the one with the shortest name. The NeoForge project made guidemod-1.0.0.jar. On the test machine the first build of each took about two minutes, and later builds about ten seconds.

To play with it, put the jar in the mods folder of a game profile with the same loader and Minecraft version. A Fabric mod built on Fabric API also needs Fabric API in that folder, because fabric.mod.json lists "fabric-api": "*" under depends.

What you see Usually because Fix
Unsupported class file major version 69, or Dependency requires at least JVM runtime version 25 Gradle runs on the wrong Java Fix “Unsupported class file major version”
A black and magenta block The texture or model path doesn’t match the id Check textures/block/<id>.png and the model’s "all" texture
The name shows as block.guidemod.ruby_block No entry in lang/en_us.json Add "block.guidemod.ruby_block": "Ruby Block"
The block drops nothing No loot table, or a 1.20.x folder name 1.21 renamed loot_tables to loot_table (Mojang, 24w21a)
A tutorial’s code doesn’t compile It was written for another version or another set of names Follow docs for your exact version; Fabric’s and NeoForge’s docs have a version picker
Gradle won’t sync after you change the version Cached files for the old version Gradle sync fails after a version change
  • MCreator makes mods through a visual editor, without writing Java at first. See Linen vs MCreator for when each fits.
  • IntelliJ IDEA with Minecraft Development is the setup Fabric’s docs recommend. See Linen vs Minecraft Development.

Linen is a desktop IDE for Minecraft mods and plugins, in private beta.

  • New mod writes the project for Fabric, Forge, NeoForge, Quilt or Legacy Fabric, on any version from 1.12.2 to 26.x, and lists every folder and file before it writes them. Free covers one mod across several loaders and versions too.
  • Linen installs the Java version the project needs.
  • Play starts the game and shows the Game Log.
  • Linen Check reads registrations, models, loot tables, names and the build, and tells you which file to change and how.
  • Claude Code, if you have it, runs in a panel beside your code and gets your mod’s loader and version. See Make a Minecraft mod with AI.

More: Getting started, Set up a Fabric mod, Set up a NeoForge mod.

Checked on 3 November 2026.