How to Install NeoForge Mods (Step-by-Step Guide 2026)

Installing mods with NeoForge is straightforward and takes about 10 minutes. Whether you are coming from Forge, trying NeoForge for the first time, or modding Minecraft for the very first time, the process follows the same basic steps: install Java, run the NeoForge installer, drop mods into a folder, and launch the game. This guide walks through every step with file paths for Windows, macOS, and Linux so nothing is left to guesswork.

Not sure what NeoForge is? Read our What Is NeoForge explainer to understand how it relates to Forge and other mod loaders.

What You Need Before Starting

• Minecraft Java Edition — purchased from minecraft.net or the Microsoft Store
• Java 21 or newer — required for Minecraft 1.20.5 and later versions
• A stable internet connection — to download the installer and mod files
• About 10 minutes — for the full setup process

Important: Launch vanilla Minecraft at least once for the version you plan to mod before installing NeoForge. This creates the version folder that the installer needs.

Step 1: Make Sure Java Is Installed

NeoForge requires Java to run. Minecraft 1.20.5 and newer need Java 21 or higher. Older NeoForge versions (1.20.2 through 1.20.4) work with Java 17.

To check your Java version:

1. Open a terminal (Command Prompt on Windows, Terminal on macOS/Linux)
2. Type java -version and press Enter
3. Look for the version number in the output

If Java is not installed or you see an older version, download the latest release from Adoptium (Eclipse Temurin) or Oracle. Install it and restart your computer before continuing.

Step 2: Download the NeoForge Installer

1. Go to the official NeoForge website at neoforged.net
2. Navigate to the Downloads section
3. Select the Minecraft version you want to mod
4. Download the Installer file (a .jar file)

Important: Always download NeoForge from the official website. Third-party reupload sites may bundle unwanted software. If the site asks you to run an .exe file instead of a .jar, you are on the wrong site.

Tip: Make sure the NeoForge version matches your Minecraft version exactly. A NeoForge installer for 1.21.1 will not work with Minecraft 1.21.4.

Step 3: Run the NeoForge Installer

1. Locate the downloaded .jar file (usually in your Downloads folder)
2. Double-click the .jar file to launch the installer. If it does not open, right-click it and select "Open with" → Java
3. In the installer window, make sure "Install client" is selected
4. Verify the installation path points to your .minecraft folder:
   • Windows: C:\Users\YourName\AppData\Roaming\.minecraft
   • macOS: ~/Library/Application Support/minecraft
   • Linux: ~/.minecraft
5. Click "OK" and wait for the installation to complete

The installer downloads the necessary NeoForge libraries and creates a new launcher profile. You should see a success message when it finishes. If the installer reports an error, make sure you have launched vanilla Minecraft for your target version at least once.

Step 4: Open the Minecraft Launcher and Select the NeoForge Profile

1. Open the Minecraft Launcher
2. Click the Installations tab at the top
3. You should see a new profile labeled something like "NeoForge [version]"
4. If it does not appear, click "New Installation", select the NeoForge version from the dropdown, and save it
5. Go back to the Play tab and select the NeoForge profile from the dropdown next to the Play button

Tip: If you use a third-party launcher like Prism Launcher, MultiMC, or ATLauncher, you can add NeoForge as a mod loader when creating a new instance. These launchers typically have built-in NeoForge support in their instance creation wizard.

Step 5: Add Mods to the Mods Folder

With NeoForge installed, you need to place mod files into the mods folder:

1. Navigate to your .minecraft folder:
   • Windows: Press Win + R, type %appdata%\.minecraft, press Enter
   • macOS: Open Finder, press Cmd + Shift + G, type ~/Library/Application Support/minecraft
   • Linux: Open your file manager and navigate to ~/.minecraft
2. Open the mods folder. If it does not exist, create it
3. Download mods from trusted sources like Modrinth or CurseForge
4. Make sure you select the NeoForge version of each mod for your specific Minecraft version
5. Place the downloaded .jar files directly into the mods folder — do not unzip them

Important: Do not place Forge-only mods into a NeoForge mods folder without checking compatibility first. While many Forge mods work on NeoForge, some do not. See the compatibility note below.

Step 6: Launch Minecraft and Verify

1. Click Play with the NeoForge profile selected
2. Wait for the game to load — the first launch with mods may take longer than usual
3. On the main menu, look for a "Mods" button. Click it to see a list of loaded mods
4. Verify that all your mods appear in the list and show a green checkmark or "loaded" status

If a mod does not appear or the game crashes on startup, check the NeoForge Mods Not Working troubleshooting guide for common fixes.

Forge Mod Compatibility Note

NeoForge shares the same API foundation as Minecraft Forge, which means many Forge mods are compatible with NeoForge. However, compatibility is not universal. Here is what to keep in mind:

• Mods with NeoForge versions: Many popular mods now publish builds specifically for NeoForge. Always look for a NeoForge-specific download on the mod's page
• Forge mods that may work: Mods that only use the public Forge API generally work on NeoForge, though this is not guaranteed
• Forge mods that may not work: Mods that rely on internal Forge APIs, certain Access Transformers, or deep Forge internals may crash or fail to load on NeoForge

When in doubt, check the mod's download page for loader compatibility information. If a mod only lists "Forge" and you experience issues on NeoForge, it may need an update from the mod developer.

Common Mistakes to Avoid

• Version mismatch: The NeoForge version, Minecraft version, and mod versions must all match. A mod built for NeoForge 1.21.1 will not work on NeoForge 1.21.4
• Missing dependencies: Some mods require library mods to function. Check each mod's description for required dependencies
• Extracting .jar files: Mod files go into the mods folder as-is. Do not unzip or extract them
• Wrong mods folder: If you have multiple Minecraft installations or use a third-party launcher, make sure you are placing mods in the correct mods folder for your NeoForge profile
• Mixing loaders: NeoForge mods, Fabric mods, and Quilt mods are not interchangeable. Only use mods built for NeoForge (or compatible Forge mods)

Other Mod Loader Guides

Using a different mod loader? Check out these installation guides:

• How to Install Forge Mods
• How to Install Fabric Mods
• How to Install Quilt Mods
• NeoForge vs Forge — Understanding the fork
• Forge vs Fabric vs NeoForge — Complete 3-way comparison

Frequently Asked Questions

Can I use Forge mods with NeoForge?

Many Forge mods work on NeoForge due to their shared API ancestry. However, some mods — particularly those that use internal Forge APIs — may not load correctly. Always check the mod's download page for a NeoForge version first.

Is NeoForge the same as Forge?

No. NeoForge is a separate project that forked from Forge in July 2023. They share the same technical foundation but are maintained by different teams with different development priorities. For more details, see our What Is NeoForge explainer.

Which NeoForge version should I use?

Use the NeoForge version that matches your target Minecraft version. For example, if you want to play Minecraft 1.21.1 with mods, download the NeoForge installer for 1.21.1. Check the mods you want to use and pick the Minecraft version that has the best mod availability.

Can I have both Forge and NeoForge installed?

Yes, but not for the same Minecraft version at the same time. You can have a Forge profile for one version and a NeoForge profile for another. Each profile has its own mods folder if you configure separate game directories.

What do I do if a mod crashes on startup?

Check the crash log for version mismatches or missing dependencies. Our NeoForge Mods Not Working guide covers the most common causes and fixes.

Ready to find mods? Check out our Best NeoForge Mods list for recommended mods across every category.

You May Also Like

How to Install Meteor Client in Minecraft (2026 Guide)

1 month ago

Best Ghost Clients for Minecraft PvP (2026)

3 weeks ago

Zinc vs Bnana vs Radon: Best DonutSMP Client (2026)

1 week ago

What Is Quilt for Minecraft? Everything You Need to Know (2026)

7 days ago

Best Minecraft Building Mods (1.21.11, 1.20.1)

6 days ago

Best Minecraft Survival Mods (1.21.11, 1.20.1)

6 days ago