FR

Serveurs de jeux

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.

10 min de lecture, mis à jour le 18 novembre 2026

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 :

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

La 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

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

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

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

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

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

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

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

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

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

L'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 :

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

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

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

Remplacez votre-domaine.com dans la ligne UA, puis rendez le script exécutable :

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

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

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

Avec NeoForge :

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

Chaque 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

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

Le 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

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 \('

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

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

Chaque joueur doit ensuite :

  1. Installer la même version de Minecraft et le même chargeur, avec l'installateur Fabric ou l'installateur NeoForge
  2. Lancer une fois le profil créé dans le launcher
  3. Copier les mods requis, dans les mêmes versions que le serveur, dans le dossier mods du 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 :

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

Mettre à jour

Sauvegardez toujours avant une mise à jour, serveur arrêté :

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

Pour mettre à jour un mod, supprimez son ancien fichier, puis relancez le script :

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

Pour 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é :

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

Le 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

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

Les 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 version
  • curl signale une erreur 404 : le nom du mod est incorrect
  • ne s'installe pas sur un serveur : ce mod va uniquement chez les joueurs
  • sha512sum: 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.