How to Create a Modded Minecraft Server with Fabric or NeoForge
Create a modded Minecraft server with Fabric or NeoForge on a Linux VPS or dedicated server: installation, server-side and client-side mods, updates and troubleshooting.
On this page
Your values
Enter them once and the commands in this guide update.
Mods add content or change how the game works. They need a loader: this guide installs Fabric or NeoForge in a separate folder, without touching your current server.
It follows on from the Create a Minecraft Server guide and reuses the minecraft user and the minecraft.service service.
By the end of this guide, you will have:
- a modded server in
/opt/minecraft/modded, started by the usual service - a script that downloads mods and verifies their integrity
- a method to determine which mods to install on the server and on the players' side
- a simple way back to your original server
Prerequisites
- A server installed with the Create a Minecraft Server guide
- Java 25, installed as described in the Install Java 25 section of the Paper guide
- SSH access with a user that has
sudoprivileges - At least 4 GB of memory for the server, and more for a large number of mods
Check Java and install the tools used in this guide:
java --version
sudo apt install -y curl jq unzipThe first command must display openjdk 25 or a higher version.
Choose Between Fabric and NeoForge
| Fabric | NeoForge | |
|---|---|---|
| Origin | Lightweight, modular loader | Project derived from Forge |
| Common base | Fabric API, required by many mods | Built into the loader |
| Launch | A single .jar file |
Installer, then dedicated Java arguments |
The right choice depends mostly on the mods you want: a mod is published for a specific loader, and a Fabric mod does not work on NeoForge, or vice versa. First check their availability on Modrinth.
Back Up and Stop the Current Server
sudo systemctl stop minecraft.service
sudo mkdir -p /opt/minecraft/backups
sudo tar -czf /opt/minecraft/backups/avant-mods-$(date +%F-%H%M).tar.gz -C /opt/minecraft server
sudo ls -lh /opt/minecraft/backupsIf you have set up Velocity, also stop velocity.service, which occupies port 25565.
Prepare the Folder
Create the folder and reuse your server's settings:
sudo -u minecraft mkdir -p /opt/minecraft/modded/mods
sudo -u minecraft cp /opt/minecraft/server/server.properties /opt/minecraft/modded/
sudo -u minecraft sed -i \
-e 's/^server-ip=.*/server-ip=/' \
-e 's/^server-port=.*/server-port=25565/' \
-e 's/^online-mode=.*/online-mode=true/' \
/opt/minecraft/modded/server.properties
echo "eula=true" | sudo -u minecraft tee /opt/minecraft/modded/eula.txtThe modded server will create a new world in /opt/minecraft/modded/world.
Then follow only one of the next two sections.
Install Fabric
Open a minecraft session, then fetch the latest stable versions of the loader and the launcher:
sudo -u minecraft bash
cd /opt/minecraft/modded
MC=26.3
LOADER=$(curl -fsSL "https://meta.fabricmc.net/v2/versions/loader/$MC" | jq -r 'map(select(.loader.stable)) | .[0].loader.version')
INSTALLER=$(curl -fsSL "https://meta.fabricmc.net/v2/versions/installer" | jq -r 'map(select(.stable)) | .[0].version')
echo "Fabric Loader $LOADER, launcher $INSTALLER"
curl -fL -o fabric-server.jar "https://meta.fabricmc.net/v2/versions/loader/$MC/$LOADER/$INSTALLER/server/jar"
ls -l fabric-server.jar
exitIf the loader version is empty or null, Fabric does not support this Minecraft version number: check it.
Next, point the service to Fabric. This file adds to minecraft.service without modifying it:
sudo mkdir -p /etc/systemd/system/minecraft.service.d
sudo nano /etc/systemd/system/minecraft.service.d/modded.conf[Service]
WorkingDirectory=/opt/minecraft/modded
ExecStart=
ExecStart=/usr/bin/java -Xms2G -Xmx4G -jar /opt/minecraft/modded/fabric-server.jar nogui
SuccessExitStatus=130 143
TimeoutStopSec=180The empty ExecStart= line cancels the original command. Adjust -Xmx to your memory, then go to Add Mods.
Install NeoForge
Open a minecraft session and look up the latest stable version for your Minecraft version. For Minecraft 26.3, NeoForge versions start with 26.3.0:
sudo -u minecraft bash
cd /opt/minecraft/modded
PREFIXE=26.3.0
MAVEN=https://maven.neoforged.net/releases/net/neoforged/neoforge
NEO=$(curl -fsSL "$MAVEN/maven-metadata.xml" | grep -F "<version>$PREFIXE." | grep -v beta | sed 's/ *<[^>]*>//g' | sort -V | tail -n 1)
echo "NeoForge $NEO"
curl -fLO "$MAVEN/$NEO/neoforge-$NEO-installer.jar"
echo "$(curl -fsSL "$MAVEN/$NEO/neoforge-$NEO-installer.jar.sha256") neoforge-$NEO-installer.jar" | sha256sum -c -
java -jar "neoforge-$NEO-installer.jar" --installServer
printf -- '\n-Xms2G\n-Xmx4G\n' >> user_jvm_args.txt
ls
exitThe installer downloads the Minecraft server and its libraries. You should then see run.sh, user_jvm_args.txt and the libraries folder.
Point the service to NeoForge. The run.sh script starts Java with the right arguments, and it remains valid after an update:
sudo mkdir -p /etc/systemd/system/minecraft.service.d
sudo nano /etc/systemd/system/minecraft.service.d/modded.conf[Service]
WorkingDirectory=/opt/minecraft/modded
ExecStart=
ExecStart=/bin/sh /opt/minecraft/modded/run.sh nogui
SuccessExitStatus=130 143
TimeoutStopSec=180Memory is set in user_jvm_args.txt.
Add Mods
Create a script that fetches a mod from Modrinth, verifies its checksum, rejects client-only mods and reports dependencies:
sudo nano /opt/minecraft/mod-get.sh#!/bin/bash
# Downloads the latest stable version of a mod from Modrinth for the server
set -euo pipefail
MOD="${1:?Specify the mod, for example lithium}"
CHARGEUR="${2:?Specify the loader: fabric or neoforge}"
MC_VERSION="${3:?Specify the Minecraft version, for example 26.3}"
UA="mon-serveur-minecraft/1.0 (https://your-domain.com)"
API="https://api.modrinth.com/v2"
cd /opt/minecraft/modded/mods
VERSION=$(curl -fsSL -H "User-Agent: $UA" -G "$API/project/$MOD/version" \
--data-urlencode "loaders=[\"$CHARGEUR\"]" \
--data-urlencode "game_versions=[\"$MC_VERSION\"]" \
--data-urlencode "include_changelog=false" \
| jq -c 'map(select(.version_type == "release")) | .[0]')
if [ "$VERSION" = "null" ]; then
echo "No stable version of $MOD for $CHARGEUR $MC_VERSION." >&2
exit 1
fi
ENVIRONNEMENT=$(echo "$VERSION" | jq -r '.environment // "unknown"')
case "$ENVIRONNEMENT" in
client_only|singleplayer_only)
echo "$MOD cannot be installed on a server ($ENVIRONNEMENT)." >&2
exit 1
;;
esac
FICHIER=$(echo "$VERSION" | jq -c '(.files | map(select(.primary)) | .[0]) // .files[0]')
NOM=$(basename "$(echo "$FICHIER" | jq -r '.filename')")
URL=$(echo "$FICHIER" | jq -r '.url')
SHA512=$(echo "$FICHIER" | jq -r '.hashes.sha512')
curl -fL -H "User-Agent: $UA" -o "$NOM.part" "$URL"
echo "$SHA512 $NOM.part" | sha512sum -c -
mv "$NOM.part" "$NOM"
echo "$NOM is in place (environment: $ENVIRONNEMENT)."
for ID in $(echo "$VERSION" | jq -r '.dependencies[]? | select(.dependency_type == "required") | .project_id // empty'); do
echo "Required dependency: $(curl -fsSL -H "User-Agent: $UA" "$API/project/$ID" | jq -r '.slug')"
doneReplace your-domain.com on the UA line, then make the script executable:
sudo chmod 755 /opt/minecraft/mod-get.shThe name to pass to the script is the one in the mod's Modrinth address: modrinth.com/mod/lithium gives lithium. Here are two examples with Lithium, an optimization mod that works without being installed on the players' side.
With Fabric, also add Fabric API, which most mods require:
sudo -u minecraft /opt/minecraft/mod-get.sh fabric-api fabric 26.3
sudo -u minecraft /opt/minecraft/mod-get.sh lithium fabric 26.3With NeoForge:
sudo -u minecraft /opt/minecraft/mod-get.sh lithium neoforge 26.3Each .part: OK line confirms an intact download. Also install each Required dependency displayed, using the same command.
Start the Server
sudo systemctl daemon-reload
sudo systemctl start minecraft.service
sudo journalctl -u minecraft.service -fThe first startup takes longer, because the world is being created. The server is ready when the line Done (…)! For help, type "help" appears. Exit the log view with Ctrl+C.
Verify the Result
systemctl show minecraft.service -p WorkingDirectory
sudo ls -l /opt/minecraft/modded/mods
sudo journalctl -u minecraft.service --since "15 minutes ago" --no-pager | grep -iE 'fabric loader|loading [0-9]+ mods|neoforge|done \('The working directory must be /opt/minecraft/modded. With Fabric, the logs show Loading Minecraft 26.3 with Fabric Loader and the number of mods. With NeoForge, they mention NeoForge at startup. In both cases, the Done line must be present, with no mod error above it.
If you created the mc-console command with the Paper guide, it still works, because the service remains the same: sudo mc-console list.
Install Mods on the Client Side
Not all mods go in the same place. On Modrinth, each version specifies an environment, which the script displays:
| Environment | Server | Players |
|---|---|---|
client_and_server |
Yes | Yes |
server_only, dedicated_server_only |
Yes | No |
server_only_client_optional |
Yes | Optional |
client_only |
No | Yes |
client_only_server_optional |
Optional | Yes |
client_or_server |
Either one is enough | Either one is enough |
client_or_server_prefers_both |
Recommended | Recommended |
singleplayer_only |
No | Singleplayer only |
unknown |
See the mod's page | See the mod's page |
For example, Sodium is client-only, and FabricProxy-Lite is for dedicated servers only. A mod that adds blocks or items almost always has to be present on both sides.
For a Fabric mod you have already downloaded, the file can also state its side. The command displays client, server or * for both, and nothing if the field is absent, which amounts to *:
sudo unzip -p /opt/minecraft/modded/mods/MOD_NAME.jar fabric.mod.json | jq -r '.environment // empty'Each player must then:
- Install the same version of Minecraft and the same loader, with the Fabric installer or the NeoForge installer
- Launch the created profile once in the launcher
- Copy the required mods, in the same versions as the server, into the game's
modsfolder
| System | mods folder |
|---|---|
| Windows | %APPDATA%\.minecraft\mods |
| macOS | ~/Library/Application Support/minecraft/mods |
| Linux | ~/.minecraft/mods |
For a group of players, a modpack avoids version mismatches: publish a precise list, or a pack in Modrinth format that everyone imports into their launcher. If a modpack offers a "server" version, use it on the server side.
Back Up the Modded Server
The backup.sh script from the base guide does not know about this folder. Add this line to /opt/minecraft/backup.sh, after the existing tar line. The world_ prefix lets the automatic cleanup take this archive into account:
tar -czf $BACKUP_DIR/world_modded_$DATE.tar.gz -C /opt/minecraft/modded world mods config server.propertiesUpdate
Always back up before an update, with the server stopped:
sudo systemctl stop minecraft.service
sudo tar -czf /opt/minecraft/backups/modded-$(date +%F-%H%M).tar.gz -C /opt/minecraft moddedTo update a mod, delete its old file, then run the script again:
sudo ls /opt/minecraft/modded/mods
sudo -u minecraft rm /opt/minecraft/modded/mods/lithium-fabric-OLD_VERSION.jar
sudo -u minecraft /opt/minecraft/mod-get.sh lithium fabric 26.3
sudo systemctl start minecraft.serviceTo update the loader, run the commands from its installation section again, without the printf line for NeoForge, then check the memory in user_jvm_args.txt. Tell your players about the changes when a mod or the loader is also installed on their side.
Return to Your Original Server
Remove the service drop-in. Your /opt/minecraft/server folder has not been modified:
sudo systemctl stop minecraft.service
sudo rm /etc/systemd/system/minecraft.service.d/modded.conf
sudo systemctl daemon-reload
sudo systemctl start minecraft.serviceThe /opt/minecraft/modded folder stays in place: you can return to it by recreating the modded.conf file. If you use Velocity, also restart velocity.service.
Troubleshooting
sudo journalctl -u minecraft.service -n 200 --no-pager
sudo less /opt/minecraft/modded/logs/latest.logCrash reports are in /opt/minecraft/modded/crash-reports.
"Incompatible mods found!" (Fabric)
The message lists the mods involved, with lines such as requires … which is missing! or but only the wrong version is present. Install the missing dependency, often fabric-api, or get a compatible version.
"Cannot load class … in environment type SERVER"
A client-only mod is present on the server. Remove the mod named in the report. With NeoForge, the same problem often appears as NoClassDefFoundError on a net/minecraft/client/… class.
"Mod … requires …" (NeoForge)
A dependency is missing or has the wrong version. The message indicates the mod to install and the expected version.
"Mod … is present in multiple files"
With NeoForge, two versions of the same mod are in mods. Keep the most recent one. With Fabric too, keep only one file per mod.
"You are trying to connect to a server that is running NeoForge, but you are not"
The player is launching the game without NeoForge. They must install the indicated version and select that profile in the launcher.
"Your client is missing the following mods"
With NeoForge, the connection screen lists the mods the player needs to add. The mention The following mod versions do not match indicates different versions: align them with those of the server.
"Received a registry entry that is unknown to this client"
With Fabric, the client and the server do not have the same content mods. Compare the two lists, including the versions.
"Incompatible client! Please use …"
The client is not using the server's Minecraft version. Select the correct profile in the launcher.
"UnsupportedClassVersionError"
Java is too old for this server or for a mod. Check java --version, then see the Install Java 25 section.
"FAILED TO BIND TO PORT"
Another service is occupying port 25565, often Velocity. Identify it with sudo ss -ltnp | grep 25565.
The mod-get.sh script fails
No stable version: the mod does not exist for this loader and this versioncurlreports a404error: the mod name is incorrectcannot be installed on a server: this mod only goes on the players' sidesha512sum: WARNING: the download is corrupted. Run the script again
To go further, see the Fabric documentation, the NeoForge server guide and the explanation of environments on Modrinth.