How to Install Mods on Your Minecraft Server

Mods or plugins?

The two are constantly confused, but they work in completely different ways:

	Mods	Plugins
Runs on	Server and client	Server only
Players must install	Yes - exactly the same mods	No
Server software	Forge, NeoForge or Fabric	Paper, Spigot or Purpur
Typical use	New blocks, mobs, dimensions, machines	Economy, protection, minigames

If you just want new features without bothering your players, plugins are the right choice - see our guide How to Install Plugins on Your Minecraft Server.

Important: You cannot simply run mods and plugins on the same server. Hybrid software such as Mohist and Arclight exists, but it is unstable and not recommended for a server you care about.

---

Step 1 - Choose your mod loader

A mod loader is the server software that makes your mods run. There are three:

• NeoForge - the standard from Minecraft 1.20.2 onwards. Most new mods are released here first.
• Forge - the classic loader. Still used for older versions and legacy modpacks.
• Fabric - light and fast, popular for optimisation mods. Most Fabric mods also require the Fabric API mod.

Forge and NeoForge mods cannot be mixed. The exception is 1.20.1, where NeoForge can still load Forge mods. Pick one loader and download every mod for exactly that one.

Step 2 - Switch server software in the control panel

A normal Vanilla or Paper server cannot run mods. You need to switch to your chosen loader:

1. Back up your world first. Changing loader can alter or break an existing world.
2. Log in to the Potionhost control panel and select your server.
3. Go to the Startup tab and pick Forge, NeoForge or Fabric along with the Minecraft version you want.
4. Restart the server so it installs the new software.

Not sure which version to choose? Contact our support team and we will help you set it up correctly.

---

Step 3 - Download your mods

The two safe sources are Modrinth and CurseForge.

Always filter on both loader and Minecraft version before downloading. A .jar file for Fabric 1.21 will not run on NeoForge 1.20.

Also check the mod dependencies. Many mods require a helper mod such as Fabric API or Architectury - those have to sit in the folder alongside the mod itself.

Client-only mods do not belong on the server. Mods such as OptiFine, Sodium, Iris and minimap mods only run on the player side. Putting them in the server mods folder usually crashes the server on startup.

---

Step 4 - Upload to the mods folder

1. Open Files in the control panel and find the mods/ folder in your server root directory.
2. If the folder does not exist, start the server once after switching loader and it is created automatically. You can also create it yourself.
3. Upload your .jar files directly into mods/.
4. Restart the server.

Watch the console during startup. It clearly states how many mods were loaded - and if something fails, the error is right there too.

---

Step 5 - Give your players the same mods

This is the step people forget. Every player needs exactly the same mods in exactly the same versions as the server, otherwise they are rejected when they try to join.

The easiest way is to collect the mods in a profile and share it:

• Modrinth App or Prism Launcher - build a profile, export it and share the file with your players.
• CurseForge App - if you are running a ready-made modpack from there.

Remember that your players also need the same loader as the server.

---

Running a ready-made modpack?

Download the modpack server pack (not the client version) from CurseForge or Modrinth and upload its contents to your server root directory. Your players install the modpack itself in their launcher.

Many modpacks have their own RAM and startup requirements - if they are listed in the modpack description, follow them.

---

Remember RAM and Java version

Mods are far heavier than plugins:

Setup	Recommended RAM
5-15 mods	4 GB
Medium modpack	6-8 GB
Large modpack (150+ mods)	10 GB or more

The Java version also has to match the game version. If the server runs a Java that is too old it will not start at all - you can change the version under Startup in the control panel.

Minecraft version	Java
1.17 - 1.19	Java 17
1.20 - 1.21.11	Java 21
26.1 and newer	Java 25

---

Troubleshooting

Symptom	Likely cause	Fix
The server crashes on startup	A mod does not match the loader or version	Remove the mod you added last and read logs/latest.log
Mod requires ... which is missing	A missing dependency	Download the mod named in the error
The mods folder does not exist	The server has not run since the loader change	Start the server once, or create the folder yourself
Players are rejected with Mod rejections	The player does not have the same mods as the server	Share your mod list or modpack profile
The mod does nothing	It is a client-only mod	Remove it from the server and let the player install it
The server will not start after a version change	Wrong Java version	Switch to Java 21 under Startup

---

Good advice

• Add mods in small batches and restart in between - then you know what broke the server.
• Always take a backup before updating or switching loader.
• Keep every mod on the same Minecraft version - helper mods included.
• Delete old .jar files when you update a mod. Two versions of the same mod will crash the server.

Got an error you cannot decipher? Send us the contents of logs/latest.log in a ticket and we will find the culprit.