EN

Game servers

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.

10 min read, updated on 18 November 2026

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 sudo privileges
  • 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:

Terminal
java --version
sudo apt install -y curl jq unzip

The 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

Terminal
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/backups

If 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:

Terminal
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.txt

The 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:

Terminal
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
exit

If 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:

Terminal
sudo mkdir -p /etc/systemd/system/minecraft.service.d
sudo nano /etc/systemd/system/minecraft.service.d/modded.conf
Configuration
[Service]
WorkingDirectory=/opt/minecraft/modded
ExecStart=
ExecStart=/usr/bin/java -Xms2G -Xmx4G -jar /opt/minecraft/modded/fabric-server.jar nogui
SuccessExitStatus=130 143
TimeoutStopSec=180

The 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:

Terminal
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
exit

The 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:

Terminal
sudo mkdir -p /etc/systemd/system/minecraft.service.d
sudo nano /etc/systemd/system/minecraft.service.d/modded.conf
Configuration
[Service]
WorkingDirectory=/opt/minecraft/modded
ExecStart=
ExecStart=/bin/sh /opt/minecraft/modded/run.sh nogui
SuccessExitStatus=130 143
TimeoutStopSec=180

Memory 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:

Terminal
sudo nano /opt/minecraft/mod-get.sh
Terminal
#!/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')"
done

Replace your-domain.com on the UA line, then make the script executable:

Terminal
sudo chmod 755 /opt/minecraft/mod-get.sh

The 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:

Terminal
sudo -u minecraft /opt/minecraft/mod-get.sh fabric-api fabric 26.3
sudo -u minecraft /opt/minecraft/mod-get.sh lithium fabric 26.3

With NeoForge:

Terminal
sudo -u minecraft /opt/minecraft/mod-get.sh lithium neoforge 26.3

Each .part: OK line confirms an intact download. Also install each Required dependency displayed, using the same command.

Start the Server

Terminal
sudo systemctl daemon-reload
sudo systemctl start minecraft.service
sudo journalctl -u minecraft.service -f

The 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

Terminal
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 *:

Terminal
sudo unzip -p /opt/minecraft/modded/mods/MOD_NAME.jar fabric.mod.json | jq -r '.environment // empty'

Each player must then:

  1. Install the same version of Minecraft and the same loader, with the Fabric installer or the NeoForge installer
  2. Launch the created profile once in the launcher
  3. Copy the required mods, in the same versions as the server, into the game's mods folder
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:

Terminal
tar -czf $BACKUP_DIR/world_modded_$DATE.tar.gz -C /opt/minecraft/modded world mods config server.properties

Update

Always back up before an update, with the server stopped:

Terminal
sudo systemctl stop minecraft.service
sudo tar -czf /opt/minecraft/backups/modded-$(date +%F-%H%M).tar.gz -C /opt/minecraft modded

To update a mod, delete its old file, then run the script again:

Terminal
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.service

To 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:

Terminal
sudo systemctl stop minecraft.service
sudo rm /etc/systemd/system/minecraft.service.d/modded.conf
sudo systemctl daemon-reload
sudo systemctl start minecraft.service

The /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

Terminal
sudo journalctl -u minecraft.service -n 200 --no-pager
sudo less /opt/minecraft/modded/logs/latest.log

Crash 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 version
  • curl reports a 404 error: the mod name is incorrect
  • cannot be installed on a server: this mod only goes on the players' side
  • sha512sum: 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.