Key takeaways
- Four things must match: Minecraft version, loader, loader version and the mod’s build
- Almost every failed install is one of those four being wrong, not the mod being broken
- Always test in a new world before touching a save you care about
Installing mods is straightforward and it has a reputation for being difficult, mostly because the failure messages are unhelpful. A mod that does not load usually produces either nothing at all or a crash report full of stack traces, neither of which tells you that you downloaded the Fabric build for a NeoForge profile.
This is the complete process, written so that you can follow it once and then diagnose your own problems afterwards.
Step one: pick your loader
A mod loader is the thing that lets Minecraft run mods at all. You install it once per Minecraft version, and every mod you download has to be built for it.
- Fabric – lightweight, fast to update after a Minecraft release, the default for performance and client-side mods
- NeoForge – the modern continuation of Forge, where most large content mods now live
- Forge – still used for older versions and some long-running mods that have not migrated
If you have no reason to prefer one, start with Fabric. It updates fastest, and the mods most people want first – performance, visuals, quality of life – are overwhelmingly there. Our comparison of the three loaders goes into when that default is wrong.
Step two: install the loader
Download the installer from the loader’s official site, run it, and point it at your Minecraft installation. It creates a new profile in the launcher – it does not modify or replace your vanilla installation, so nothing you already have is at risk.
When it finishes, open the Minecraft launcher and check that a new profile appeared in the dropdown. Launch it once and let it reach the main menu before installing any mods. If it does not start, the problem is the loader and adding mods will only make it harder to diagnose.
Step three: find the mods folder
Running the modded profile once creates a mods folder inside your Minecraft directory. If it is not there, create it manually with exactly that name.
- Windows: press Windows and R, type the appdata shortcut for Minecraft, and open the .minecraft folder
- macOS: it is in the Application Support folder inside your user Library
- Linux: a hidden .minecraft folder in your home directory
On any launcher that manages instances separately – Prism, MultiMC, the Modrinth launcher – each instance has its own mods folder, and that is the one to use.
Step four: download the right build
This is where installs fail. On a mod’s download page you choose a Minecraft version and a loader, and the file you get is specific to both. A file for 1.21 will not load on 1.21.4, and a Fabric file will not load on NeoForge.
Check the filename after downloading. Most mods include the version and loader in it, and reading it takes two seconds compared to twenty minutes of crash-report archaeology.
Dependencies
Many Fabric mods require Fabric API, which is a separate download. Some mods require a specific library mod – the mod page always says so, usually near the top. Missing dependencies are the second most common cause of a failed launch after version mismatch.
Step five: drop the files in and launch
Put the jar files in the mods folder without unzipping them. A mod you have extracted will not work. Then launch the modded profile.
If it reaches the main menu, check the mods list in-game to confirm everything loaded. If it crashes, the crash report names the mod that caused it more often than people expect – look for a filename you recognise rather than reading the whole trace.
Step six: test before you commit
Create a new world and play for a few minutes before loading a save you care about. Some mods change world generation, some add blocks that will not exist if you later remove the mod, and both of those are much easier to discover in a throwaway world.
- Back up your save folder before adding mods to an existing world
- Worldgen mods only affect newly generated chunks – see our guide to adding them safely
- Removing a block-adding mod later will leave holes where its blocks were
When something goes wrong
Work through it in this order, because it resolves the large majority of cases before you get to the difficult ones.
- Confirm the Minecraft version, loader and mod build all match
- Confirm Fabric API or any named dependency is present
- Remove all mods, then add them back in groups to find the culprit
- Check the mod’s page for known conflicts with something else you have installed
- Read the crash report for a filename you recognise before reading anything else
Servers
Any mod that adds blocks, items or entities must be installed on both the server and every client. Purely visual and client-side mods – shaders, interface tweaks, performance mods – only need to be on your own machine. If you are unsure which category a mod is in, its page will say.
Where to start
If this is your first install, a performance mod is the right first mod: it is client-side, it cannot break a world, and the benefit is immediate. Our performance mod roundup covers which ones actually do something, and the Iris installation walkthrough is the natural next step once you want shaders.