How to Update an Existing Mod Project to NeoForge

If you already have a working mod project, the official path to NeoForge is to update your build script using the MDK (Mod Development Kit) list as your reference. The NeoForged site points existing mod projects to that MDK list for examples of how to update a build script to use NeoForge, and recommends the project's Documentation and the Modding Wiki for learning the details. This applies to developers with an existing mod project who want to migrate or update it; if you are starting from scratch instead, the site directs you to the Mod Generator page.

What you need before starting

• A current mod project with a build script you can edit (the site does not specify a particular build tool, so use whatever your project already uses).
• The NeoForge version that matches your target Minecraft version. The installer page lists Minecraft Version and NeoForge Version selectors, and the news archive shows releases tied to specific Minecraft versions (for example, NeoForge 21.11 for Minecraft 1.21.11, and NeoForge 21.9 for Minecraft 1.21.9).
• Access to the MDK list, Documentation, and Modding Wiki from neoforged.net.

Steps to update the build script

1. Open the MDK list on neoforged.net. This is the reference the site provides specifically for existing mod projects updating their build script to use NeoForge.
2. Compare your current build script against the MDK examples. Identify the dependency, plugin, and configuration entries that differ from the NeoForge setup.
3. Update your build script to match the NeoForge pattern shown in the MDK examples, keeping your own project's names, versions, and structure.
4. Set the NeoForge version for your target Minecraft version. Use the installer page's version selectors to confirm which NeoForge build corresponds to the Minecraft version you are targeting.
5. Run your build and resolve errors. The expected result is a project that resolves NeoForge dependencies and compiles under the updated script.
6. Consult the Documentation and Modding Wiki for migration points that go beyond the build script, such as API changes between versions.

Version-specific migration notes

NeoForge changes APIs between releases, and the news posts document some of these. Check the post for the version you are moving to before you finish migrating:

If your mod uses the transfer APIs, read "The Transfer Rework" before migrating, since it explains both the new system and the migration path from the old one. If your mod sends serverbound packets, read "Mitigating Network Vulnerabilities" for the mitigation guidance.

Common sticking points

• Mismatched versions. The installer page separates Minecraft Version from NeoForge Version. Pick the NeoForge build that corresponds to your Minecraft version rather than the newest build overall.
• Build script drift. The MDK list is examples, not a drop-in replacement. Update the relevant entries in your own script instead of replacing the whole file.
• API changes beyond the build script. A successful compile does not mean the mod behaves the same. Use the version-specific news posts and the Documentation to catch behavioral changes.
• Starting fresh by mistake. If you have no current mod project, the site's guidance is different: use the Mod Generator page, download and unzip the generated mod, and begin there.

Where to go next

• MDK list — build script examples for existing projects.
• Documentation and Modding Wiki — learning and migration reference.
• Installer files page — Minecraft and NeoForge version selectors.
• News archive — release notes and API change write-ups per version.