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 do you need before you start?
Section titled “What do you need before you start?”| 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.
Step 1: Which loader should you pick?
Section titled “Step 1: Which loader should you pick?”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.
Step 3: Which JDK do you install?
Section titled “Step 3: Which JDK do you install?”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.
Step 4: How do you create the project?
Section titled “Step 4: How do you create the project?”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.
What is in a new mod project?
Section titled “What is in a new mod project?”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.
What should the mod id be?
Section titled “What should the mod id be?”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.
Step 5: What does the main class do?
Section titled “Step 5: What does the main class do?”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); }}Step 6: How do you add your first block?
Section titled “Step 6: How do you add your first block?”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?”./gradlew runClientOn 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.0The 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).
Step 8: How do you build the mod jar?
Section titled “Step 8: How do you build the mod jar?”./gradlew buildThe 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 goes wrong in a first mod?
Section titled “What goes wrong in a first mod?”| 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 |
Are there other ways to make a mod?
Section titled “Are there other ways to make a mod?”- 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.
In Linen
Section titled “In Linen”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.
Sources
Section titled “Sources”Checked on 3 November 2026.
- Mojang, version manifest and version JSONs (
javaVersion): piston-meta.mojang.com/mc/game/version_manifest_v2.json - Fabric: Setting up a Development Environment (1.21.1), Creating a Project, Launching the Game (1.21.1), Building a Mod, Fabric for Minecraft 26.1, fabric.mod.json specification
- NeoForge: Getting Started (1.21.1), Mod Files (1.21.1)
- Forge: Getting Started with Forge
- Mojang: Minecraft Snapshot 24w21a (data pack folder renames)
- Modrinth search API, mod counts per version: api.modrinth.com/v2/search