Port a Forge mod to NeoForge
NeoForge began as a fork of Forge, so a Forge mod ports to it step by step. Most of the work comes from changes NeoForge made in its own releases since then. NeoForge doesn’t support 1.20.1, so a Forge 1.20.1 mod moves to NeoForge on 1.20.2 or newer, usually straight to the version you want to support.
Checked on 19 November 2026 against NeoForge’s release posts, linked under Sources.
Staying on 1.20.1 for now
Section titled “Staying on 1.20.1 for now”NeoForge recommends the legacy plugin of ModDevGradle for mods that stay on Forge 1.17 to 1.20.1. It builds Forge mods with a build script close to NeoForge’s, so a later port changes less of it.
From Forge to NeoForge (1.20.2)
Section titled “From Forge to NeoForge (1.20.2)”- Packages move from Forge’s to
net.neoforged, and NeoForge renamed some classes. Its 20.2 release post links the full list and a script that remaps Java mods. - The loader’s mod id is
neoforge. Dependencies in your mod’s metadata point atneoforgeinstead offorge. - The build uses NeoForge’s MDK and Mojang’s names everywhere. Start from the new MDK’s build script.
NeoForge 1.20.5 and newer
Section titled “NeoForge 1.20.5 and newer”- Rename
META-INF/mods.tomltoMETA-INF/neoforge.mods.toml. NeoForge skips a jar without it, with no error, so updateprocessResourcesin the build too. See Missing mods.toml. - Java 21:
JavaLanguageVersion.of(21). - Events:
@Mod.EventBusSubscriberbecomes@EventBusSubscriber,Bus.FORGEbecomesBus.GAME, and the game bus isNeoForge.EVENT_BUS. - Networking: register payloads in
RegisterPayloadHandlersEventwith aPayloadRegistrar. Each payload has aCustomPacketPayload.Typeand aStreamCodec, and you send it withPacketDistributor. Handlers run on the main thread unless you choose otherwise. - Items keep data in data components, no longer in a
CompoundTagon the stack. BlockEntity.save(CompoundTag)becomessaveAdditional(CompoundTag, HolderLookup.Provider).- HUD overlays:
RegisterGuiOverlaysEventbecomesRegisterGuiLayersEvent. - Shared tags use the
cnamespace, such asc:ores/tin.
Minecraft 26.1 and newer
Section titled “Minecraft 26.1 and newer”26.1 needs Java 25 and Gradle 9.1.0 or newer, and NeoForge versions have four parts, such as 26.1.0.10-beta. See
Port a mod to 26.1 and NeoForge’s 26.1 notes.
In Linen
Section titled “In Linen”Linen opens Forge and NeoForge mods side by side. The share code between Fabric and NeoForge how-to covers keeping one mod on several loaders.