Comment créer un serveur Minecraft moddé avec Fabric ou NeoForge
Créez un serveur Minecraft moddé avec Fabric ou NeoForge sur un VPS ou un serveur dédié Linux : installation, mods côté serveur et côté client, mises à jour et dépannage.
Sur cette page
Vos valeurs
Renseignez-les une fois, les commandes du guide se mettent à jour.
Les mods ajoutent du contenu ou modifient le fonctionnement du jeu. Ils ont besoin d'un chargeur : ce guide installe Fabric ou NeoForge dans un dossier séparé, sans toucher à votre serveur actuel.
Il prolonge le guide Créer un serveur Minecraft et réutilise l'utilisateur minecraft ainsi que le service minecraft.service.
À la fin de ce guide, vous aurez :
- un serveur moddé dans
/opt/minecraft/modded, lancé par le service habituel - un script qui télécharge les mods et contrôle leur intégrité
- une méthode pour savoir quels mods installer sur le serveur et chez les joueurs
- un retour simple à votre serveur d'origine
Prérequis
- Un serveur installé avec le guide Créer un serveur Minecraft
- Java 25, à installer comme indiqué dans la section Installer Java 25 du guide Paper
- Un accès SSH avec un utilisateur disposant de
sudo - Au moins 4 Go de mémoire pour le serveur, et davantage pour un grand nombre de mods
Vérifiez Java et installez les outils utilisés par ce guide :
java --version
sudo apt install -y curl jq unzipLa première commande doit afficher openjdk 25 ou une version supérieure.
Choisir entre Fabric et NeoForge
| Fabric | NeoForge | |
|---|---|---|
| Origine | Chargeur léger et modulaire | Projet issu de Forge |
| Base commune | Fabric API, requise par beaucoup de mods | Intégrée au chargeur |
| Lancement | Un fichier .jar |
Installateur, puis arguments Java dédiés |
Le bon choix dépend surtout des mods que vous voulez : un mod est publié pour un chargeur précis, et un mod Fabric ne fonctionne pas sur NeoForge, ni l'inverse. Vérifiez d'abord leur disponibilité sur Modrinth.
Sauvegarder et arrêter le serveur actuel
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/backupsSi vous avez mis en place Velocity, arrêtez aussi velocity.service, qui occupe le port 25565.
Préparer le dossier
Créez le dossier et reprenez les réglages de votre serveur :
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.txtLe serveur moddé créera un nouveau monde dans /opt/minecraft/modded/world.
Suivez ensuite une seule des deux sections suivantes.
Installer Fabric
Ouvrez une session minecraft, puis récupérez les dernières versions stables du chargeur et du lanceur :
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, lanceur $INSTALLER"
curl -fL -o fabric-server.jar "https://meta.fabricmc.net/v2/versions/loader/$MC/$LOADER/$INSTALLER/server/jar"
ls -l fabric-server.jar
exitSi la version du chargeur est vide ou vaut null, Fabric ne prend pas en charge ce numéro de Minecraft : vérifiez-le.
Faites ensuite pointer le service vers Fabric. Ce fichier complète minecraft.service sans le modifier :
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=180La ligne ExecStart= vide annule la commande d'origine. Adaptez -Xmx à votre mémoire, puis passez à Ajouter des mods.
Installer NeoForge
Ouvrez une session minecraft et cherchez la dernière version stable pour votre version de Minecraft. Pour Minecraft 26.3, les versions de NeoForge commencent par 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
exitL'installateur télécharge le serveur Minecraft et ses bibliothèques. Vous devez ensuite voir run.sh, user_jvm_args.txt et le dossier libraries.
Faites pointer le service vers NeoForge. Le script run.sh lance Java avec les bons arguments, et il reste valable après une mise à jour :
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=180La mémoire se règle dans user_jvm_args.txt.
Ajouter des mods
Créez un script qui récupère un mod depuis Modrinth, contrôle son empreinte, écarte les mods réservés au client et signale les dépendances :
sudo nano /opt/minecraft/mod-get.sh#!/bin/bash
# Télécharge depuis Modrinth la dernière version stable d'un mod pour le serveur
set -euo pipefail
MOD="${1:?Indiquez le mod, par exemple lithium}"
CHARGEUR="${2:?Indiquez le chargeur : fabric ou neoforge}"
MC_VERSION="${3:?Indiquez la version de Minecraft, par exemple 26.3}"
UA="mon-serveur-minecraft/1.0 (https://votre-domaine.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 "Aucune version stable de $MOD pour $CHARGEUR $MC_VERSION." >&2
exit 1
fi
ENVIRONNEMENT=$(echo "$VERSION" | jq -r '.environment // "unknown"')
case "$ENVIRONNEMENT" in
client_only|singleplayer_only)
echo "$MOD ne s'installe pas sur un serveur ($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 est en place (environnement : $ENVIRONNEMENT)."
for ID in $(echo "$VERSION" | jq -r '.dependencies[]? | select(.dependency_type == "required") | .project_id // empty'); do
echo "Dépendance requise : $(curl -fsSL -H "User-Agent: $UA" "$API/project/$ID" | jq -r '.slug')"
doneRemplacez votre-domaine.com dans la ligne UA, puis rendez le script exécutable :
sudo chmod 755 /opt/minecraft/mod-get.shLe nom à donner au script est celui de l'adresse du mod sur Modrinth : modrinth.com/mod/lithium donne lithium. Voici deux exemples, avec Lithium, un mod d'optimisation qui fonctionne sans être installé chez les joueurs.
Avec Fabric, ajoutez aussi Fabric API, requise par la plupart des mods :
sudo -u minecraft /opt/minecraft/mod-get.sh fabric-api fabric 26.3
sudo -u minecraft /opt/minecraft/mod-get.sh lithium fabric 26.3Avec NeoForge :
sudo -u minecraft /opt/minecraft/mod-get.sh lithium neoforge 26.3Chaque ligne .part: OK confirme un téléchargement intact. Installez aussi chaque Dépendance requise affichée, avec la même commande.
Démarrer le serveur
sudo systemctl daemon-reload
sudo systemctl start minecraft.service
sudo journalctl -u minecraft.service -fLe premier démarrage est plus long, car le monde est créé. Le serveur est prêt à la ligne Done (…)! For help, type "help". Quittez le suivi avec Ctrl+C.
Vérifier le résultat
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 \('Le dossier de travail doit être /opt/minecraft/modded. Avec Fabric, le journal affiche Loading Minecraft 26.3 with Fabric Loader et le nombre de mods. Avec NeoForge, il mentionne NeoForge au démarrage. Dans les deux cas, la ligne Done doit être présente, sans erreur de mod au-dessus.
Si vous aviez créé la commande mc-console avec le guide Paper, elle fonctionne toujours, car le service reste le même : sudo mc-console list.
Installer les mods côté client
Tous les mods ne vont pas au même endroit. Sur Modrinth, chaque version indique un environnement, affiché par le script :
| Environnement | Serveur | Joueurs |
|---|---|---|
client_and_server |
Oui | Oui |
server_only, dedicated_server_only |
Oui | Non |
server_only_client_optional |
Oui | Facultatif |
client_only |
Non | Oui |
client_only_server_optional |
Facultatif | Oui |
client_or_server |
L'un ou l'autre suffit | L'un ou l'autre suffit |
client_or_server_prefers_both |
Conseillé | Conseillé |
singleplayer_only |
Non | Solo uniquement |
unknown |
Consultez la page du mod | Consultez la page du mod |
Par exemple, Sodium est réservé au client, FabricProxy-Lite au serveur dédié. Un mod qui ajoute des blocs ou des objets doit presque toujours être présent des deux côtés.
Pour un mod Fabric déjà téléchargé, le fichier peut aussi renseigner son côté. La commande affiche client, server ou * pour les deux, et rien si le champ est absent, ce qui revient à * :
sudo unzip -p /opt/minecraft/modded/mods/NOM_DU_MOD.jar fabric.mod.json | jq -r '.environment // empty'Chaque joueur doit ensuite :
- Installer la même version de Minecraft et le même chargeur, avec l'installateur Fabric ou l'installateur NeoForge
- Lancer une fois le profil créé dans le launcher
- Copier les mods requis, dans les mêmes versions que le serveur, dans le dossier
modsdu jeu
| Système | Dossier mods |
|---|---|
| Windows | %APPDATA%\.minecraft\mods |
| macOS | ~/Library/Application Support/minecraft/mods |
| Linux | ~/.minecraft/mods |
Pour un groupe de joueurs, un modpack évite les écarts de version : publiez une liste précise, ou un pack au format Modrinth que chacun importe dans son launcher. Si un modpack propose une version « serveur », utilisez-la côté serveur.
Sauvegarder le serveur moddé
Le script backup.sh du guide de base ne connaît pas ce dossier. Ajoutez cette ligne à /opt/minecraft/backup.sh, après la ligne tar existante. Le préfixe world_ permet au nettoyage automatique de la prendre en compte :
tar -czf $BACKUP_DIR/world_modded_$DATE.tar.gz -C /opt/minecraft/modded world mods config server.propertiesMettre à jour
Sauvegardez toujours avant une mise à jour, serveur arrêté :
sudo systemctl stop minecraft.service
sudo tar -czf /opt/minecraft/backups/modded-$(date +%F-%H%M).tar.gz -C /opt/minecraft moddedPour mettre à jour un mod, supprimez son ancien fichier, puis relancez le script :
sudo ls /opt/minecraft/modded/mods
sudo -u minecraft rm /opt/minecraft/modded/mods/lithium-fabric-ANCIENNE_VERSION.jar
sudo -u minecraft /opt/minecraft/mod-get.sh lithium fabric 26.3
sudo systemctl start minecraft.servicePour mettre à jour le chargeur, relancez les commandes de sa section d'installation, sans la ligne printf pour NeoForge, puis contrôlez la mémoire dans user_jvm_args.txt. Communiquez les changements aux joueurs quand un mod ou le chargeur est aussi installé chez eux.
Revenir à votre serveur d'origine
Retirez le complément du service. Votre dossier /opt/minecraft/server n'a pas été modifié :
sudo systemctl stop minecraft.service
sudo rm /etc/systemd/system/minecraft.service.d/modded.conf
sudo systemctl daemon-reload
sudo systemctl start minecraft.serviceLe dossier /opt/minecraft/modded reste en place : vous pouvez y revenir en recréant le fichier modded.conf. Si vous utilisez Velocity, redémarrez aussi velocity.service.
En cas de problème
sudo journalctl -u minecraft.service -n 200 --no-pager
sudo less /opt/minecraft/modded/logs/latest.logLes rapports de plantage sont dans /opt/minecraft/modded/crash-reports.
« Incompatible mods found! » (Fabric)
Le message liste les mods concernés, avec des lignes comme requires … which is missing! ou but only the wrong version is present. Installez la dépendance manquante, souvent fabric-api, ou prenez une version compatible.
« Cannot load class … in environment type SERVER »
Un mod réservé au client est présent sur le serveur. Retirez le mod cité dans le rapport. Avec NeoForge, le même problème apparaît souvent sous la forme NoClassDefFoundError sur une classe net/minecraft/client/….
« Mod … requires … » (NeoForge)
Une dépendance manque ou n'a pas la bonne version. Le message indique le mod à installer et la version attendue.
« Mod … is present in multiple files »
Avec NeoForge, deux versions du même mod se trouvent dans mods. Gardez la plus récente. Avec Fabric aussi, ne conservez qu'un fichier par mod.
« You are trying to connect to a server that is running NeoForge, but you are not »
Le joueur lance le jeu sans NeoForge. Il doit installer la version indiquée et choisir ce profil dans le launcher.
« Your client is missing the following mods »
Avec NeoForge, l'écran de connexion liste les mods à ajouter chez le joueur. La mention The following mod versions do not match signale des versions différentes : alignez-les sur celles du serveur.
« Received a registry entry that is unknown to this client »
Avec Fabric, le client et le serveur n'ont pas les mêmes mods de contenu. Comparez les deux listes, y compris les versions.
« Incompatible client! Please use … »
Le client n'utilise pas la version de Minecraft du serveur. Sélectionnez le bon profil dans le launcher.
« UnsupportedClassVersionError »
Java est trop ancien pour ce serveur ou pour un mod. Contrôlez java --version, puis la section Installer Java 25.
« FAILED TO BIND TO PORT »
Un autre service occupe le port 25565, souvent Velocity. Repérez-le avec sudo ss -ltnp | grep 25565.
Le script mod-get.sh échoue
Aucune version stable: le mod n'existe pas pour ce chargeur et cette versioncurlsignale une erreur404: le nom du mod est incorrectne s'installe pas sur un serveur: ce mod va uniquement chez les joueurssha512sum: WARNING: le téléchargement est corrompu. Relancez le script
Pour aller plus loin, consultez la documentation de Fabric, le guide serveur de NeoForge et l'explication des environnements sur Modrinth.