Skip to content

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.

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.

  • 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 at neoforge instead of forge.
  • The build uses NeoForge’s MDK and Mojang’s names everywhere. Start from the new MDK’s build script.
  • Rename META-INF/mods.toml to META-INF/neoforge.mods.toml. NeoForge skips a jar without it, with no error, so update processResources in the build too. See Missing mods.toml.
  • Java 21: JavaLanguageVersion.of(21).
  • Events: @Mod.EventBusSubscriber becomes @EventBusSubscriber, Bus.FORGE becomes Bus.GAME, and the game bus is NeoForge.EVENT_BUS.
  • Networking: register payloads in RegisterPayloadHandlersEvent with a PayloadRegistrar. Each payload has a CustomPacketPayload.Type and a StreamCodec, and you send it with PacketDistributor. Handlers run on the main thread unless you choose otherwise.
  • Items keep data in data components, no longer in a CompoundTag on the stack.
  • BlockEntity.save(CompoundTag) becomes saveAdditional(CompoundTag, HolderLookup.Provider).
  • HUD overlays: RegisterGuiOverlaysEvent becomes RegisterGuiLayersEvent.
  • Shared tags use the c namespace, such as c:ores/tin.

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.

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.