Comment installer et mettre à jour des plugins sur un serveur Minecraft Paper
Passez votre serveur Minecraft vanilla à Paper sans perdre le monde, puis installez et mettez à jour vos plugins sur un VPS ou un serveur dédié Linux.
Sur cette page
Vos valeurs
Renseignez-les une fois, les commandes du guide se mettent à jour.
Le serveur Minecraft officiel (vanilla) ne charge pas de plugins. Ce guide vous explique comment le remplacer par Paper en conservant votre monde, puis comment installer et mettre à jour des plugins proprement.
Il prolonge le guide Créer un serveur Minecraft et réutilise ses éléments : l'utilisateur minecraft, le dossier /opt/minecraft/server, le fichier server.jar et le service minecraft.service.
À la fin de ce guide, vous aurez :
- Java 25 et Paper à la place du serveur vanilla, avec votre monde intact
- une commande
mc-consolepour parler à la console du serveur lancé par systemd - un premier plugin installé et une méthode de mise à jour sûre
Prérequis
- Un serveur installé avec le guide Créer un serveur Minecraft
- Un accès SSH avec un utilisateur disposant de
sudo - Assez d'espace disque pour une copie complète du dossier du serveur
Vérifier votre serveur actuel
Regardez d'abord quelle version de Minecraft tourne et si le serveur est déjà sous Paper :
sudo grep -m1 'Starting minecraft server version' /opt/minecraft/server/logs/latest.log
unzip -l /opt/minecraft/server/server.jar | grep -q 'io/papermc/paperclip/Main.class' && echo Paper || echo VanillaSi la seconde commande affiche Paper, votre serveur est déjà migré : sauvegardez-le, puis passez directement à l'activation de la console.
Arrêter et sauvegarder le serveur
Arrêtez le serveur, vérifiez l'espace disponible, puis créez une archive complète :
sudo systemctl stop minecraft.service
sudo du -sh /opt/minecraft/server
df -h /opt/minecraft
sudo mkdir -p /opt/minecraft/backups
sudo tar -czf /opt/minecraft/backups/avant-paper-$(date +%F-%H%M).tar.gz -C /opt/minecraft server
sudo ls -lh /opt/minecraft/backupsSi vous lancez le serveur dans screen, tapez stop dans sa console au lieu de la première commande.
Installer Java 25
Paper recommande Amazon Corretto, disponible pour Debian et Ubuntu. Ajoutez son dépôt, puis installez Java 25 :
sudo apt update
sudo apt install -y ca-certificates apt-transport-https gnupg wget curl jq
wget -O - https://apt.corretto.aws/corretto.key | sudo gpg --dearmor --yes -o /usr/share/keyrings/corretto-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/corretto-keyring.gpg] https://apt.corretto.aws stable main" | sudo tee /etc/apt/sources.list.d/corretto.list
sudo apt update
sudo apt install -y java-25-amazon-corretto-jdk libxi6 libxtst6 libxrender1Le service lance /usr/bin/java. Si Java 21 est aussi installé, faites pointer cette commande vers Java 25 :
sudo update-alternatives --set java "$(update-alternatives --list java | grep -m1 'java-25')"
java --versionLa sortie doit commencer par openjdk 25.
Passer à Paper sans perdre le monde
Le passage consiste à remplacer server.jar par le fichier de Paper. Comme le nom reste identique, le service systemd n'a pas besoin de changer, et votre dossier world, server.properties et vos listes de joueurs restent en place.
Créez un script qui télécharge le dernier build stable, contrôle son empreinte et remplace server.jar. Il resservira pour chaque mise à jour :
sudo nano /opt/minecraft/paper-update.sh#!/bin/bash
# Télécharge le dernier build stable de Paper et remplace server.jar
set -euo pipefail
MC_VERSION="${1:?Indiquez la version de Minecraft, par exemple 26.3}"
UA="mon-serveur-minecraft/1.0 (https://votre-domaine.com)"
API="https://fill.papermc.io/v3/projects/paper/versions/$MC_VERSION/builds"
cd /opt/minecraft/server
BUILD=$(curl -fsSL -H "User-Agent: $UA" "$API" | jq -c 'map(select(.channel == "STABLE")) | .[0]')
if [ "$BUILD" = "null" ]; then
echo "Aucun build stable trouvé pour Minecraft $MC_VERSION." >&2
exit 1
fi
URL=$(echo "$BUILD" | jq -r '.downloads."server:default".url')
SHA256=$(echo "$BUILD" | jq -r '.downloads."server:default".checksums.sha256')
curl -fL -H "User-Agent: $UA" -o server.jar.new "$URL"
echo "$SHA256 server.jar.new" | sha256sum -c -
if [ -f server.jar ]; then
mv server.jar server.jar.old
fi
mv server.jar.new server.jar
echo "Paper $MC_VERSION, build $(echo "$BUILD" | jq -r '.id'), est en place."Dans la ligne UA, remplacez votre-domaine.com par l'adresse de votre site ou par un moyen de vous contacter : l'API de Paper demande un User-Agent qui identifie votre projet et indique un contact.
Rendez le script exécutable, puis lancez-le avec l'utilisateur minecraft :
sudo chmod 755 /opt/minecraft/paper-update.sh
sudo -u minecraft /opt/minecraft/paper-update.sh 26.3La ligne server.jar.new: OK confirme que le fichier téléchargé est intact. L'ancien serveur est conservé sous le nom server.jar.old.
Activer la console du service
Le service du guide de base contient StandardInput=null : il n'a donc aucune console, alors que beaucoup de plugins se configurent par des commandes. Vous allez lui en donner une avec une file nommée, sans ouvrir de port réseau.
Créez l'unité qui porte la file :
sudo nano /etc/systemd/system/minecraft.socket[Unit]
Description=Console du serveur Minecraft
PartOf=minecraft.service
[Socket]
ListenFIFO=/run/minecraft.stdin
SocketMode=0600Seul root peut écrire dans cette file, d'où le sudo devant mc-console.
Ajoutez ensuite un complément au service. Ce fichier s'ajoute à minecraft.service sans le modifier :
sudo mkdir -p /etc/systemd/system/minecraft.service.d
sudo nano /etc/systemd/system/minecraft.service.d/console.conf[Unit]
Requires=minecraft.socket
After=minecraft.socket
[Service]
Sockets=minecraft.socket
StandardInput=socket
StandardOutput=journal
StandardError=journal
SuccessExitStatus=130 143
TimeoutStopSec=180SuccessExitStatus évite que le service apparaisse en échec après un arrêt normal, et TimeoutStopSec laisse trois minutes au serveur pour enregistrer le monde.
Créez enfin la commande mc-console, qui envoie une commande au serveur et affiche sa réponse :
sudo nano /usr/local/bin/mc-console#!/bin/bash
# Envoie une commande à la console Minecraft et affiche la réponse du journal
if [ "$#" -eq 0 ]; then
echo "Usage : mc-console <commande>" >&2
exit 1
fi
if ! systemctl is-active --quiet minecraft.service; then
echo "Le service minecraft.service n'est pas démarré." >&2
exit 1
fi
DEBUT=$(date '+%Y-%m-%d %H:%M:%S')
printf '%s\n' "$*" > /run/minecraft.stdin
sleep "${MC_CONSOLE_WAIT:-2}"
journalctl -u minecraft.service --since "$DEBUT" --no-pager -o catsudo chmod 755 /usr/local/bin/mc-console
sudo systemctl daemon-reloadDémarrer Paper
sudo systemctl start minecraft.service
sudo journalctl -u minecraft.service -fLe premier démarrage est plus long : Paper télécharge les fichiers de Minecraft, puis convertit le monde. Il affiche World storage migration is required during startup et attend 30 secondes avant de continuer, ce qui vous laisse le temps d'interrompre le démarrage si vous n'avez pas de sauvegarde.
Le serveur est prêt quand la ligne Done (…)! For help, type "help" apparaît. Quittez le suivi du journal avec Ctrl+C : le serveur continue de tourner.
Vérifier le résultat
sudo mc-console version
sudo mc-console plugins
sudo ls /opt/minecraft/server /opt/minecraft/server/worldVous devez obtenir :
- une ligne
This server is running Paper version 26.3-… Server Plugins (0), car aucun plugin n'est encore installé- les nouveaux fichiers
bukkit.yml,spigot.ymlet le dossierconfig, ainsi que votre dossierworld
Les dossiers plugins/spark et plugins/bStats sont créés par Paper lui-même : c'est normal. Connectez-vous enfin au serveur avec votre client Minecraft et vérifiez que vos constructions sont bien là.
Installer un plugin
Choisir un plugin compatible
Avant de télécharger un plugin, vérifiez trois points sur sa page :
- il est prévu pour Paper (ou Spigot/Bukkit), pas pour Fabric ou Forge, qui sont des mods
- il annonce la prise en charge de votre version de Minecraft
- ses dépendances éventuelles sont indiquées, car elles doivent être installées aussi
Téléchargez uniquement depuis des sources fiables : Hangar, le dépôt de plugins de Paper, Modrinth, ou le site et le dépôt GitHub officiels du projet. Un plugin s'exécute avec les droits de l'utilisateur minecraft et peut lire tout le dossier du serveur.
Installer depuis Hangar
L'exemple ci-dessous installe Chunky, un plugin de prégénération du monde. Commencez par regarder sa dernière version et les versions de Minecraft prises en charge :
sudo -u minecraft bash
cd /opt/minecraft/server/plugins
UA="mon-serveur-minecraft/1.0 (https://votre-domaine.com)"
API="https://hangar.papermc.io/api/v1/projects/Chunky/versions?limit=1&channel=Release&platform=PAPER"
curl -fsSL -H "User-Agent: $UA" "$API" | jq '.result[0] | {version: .name, minecraft: .platformDependencies.PAPER, fichier: .downloads.PAPER.fileInfo.name}'Si votre version de Minecraft figure dans la liste, téléchargez le fichier et quittez la session minecraft :
URL=$(curl -fsSL -H "User-Agent: $UA" "$API" | jq -r '.result[0].downloads.PAPER.downloadUrl')
curl -fLO -H "User-Agent: $UA" "$URL"
ls -l
exitSi l'adresse vaut null, le plugin est hébergé ailleurs : suivez le lien indiqué sur sa page Hangar.
Installer depuis votre ordinateur
Envoyez le fichier .jar sur le serveur, puis placez-le dans le dossier plugins avec le bon propriétaire :
scp MonPlugin.jar VOTRE_USER@IP_SERVEUR:/tmp/sudo install -o minecraft -m 644 /tmp/MonPlugin.jar /opt/minecraft/server/plugins/Le fichier doit se trouver directement dans plugins : Paper ne lit pas les sous-dossiers. Si le téléchargement est une archive .zip, extrayez-la et gardez le .jar prévu pour Paper ou Bukkit.
Charger le plugin
Redémarrez le serveur, attendez la ligne Done, puis listez les plugins :
sudo systemctl restart minecraft.service
sudo journalctl -u minecraft.service -fsudo mc-console pluginsUn plugin chargé apparaît en vert en jeu avec /plugins. Dans le journal, il est listé sans message d'erreur au démarrage.
Sa configuration se trouve ensuite dans /opt/minecraft/server/plugins/<NomDuPlugin>/. Modifiez-la avec l'utilisateur minecraft, puis redémarrez le serveur ou utilisez la commande de rechargement propre au plugin.
Mettre à jour les plugins
Paper sait remplacer les plugins au démarrage grâce au dossier plugins/update. Vous n'avez donc rien à supprimer à la main.
Sauvegardez d'abord les plugins et leur configuration :
sudo tar -czf /opt/minecraft/backups/plugins-$(date +%F-%H%M).tar.gz -C /opt/minecraft/server pluginsDéposez ensuite la nouvelle version dans update. Voici l'exemple de Chunky :
sudo -u minecraft bash
mkdir -p /opt/minecraft/server/plugins/update
cd /opt/minecraft/server/plugins/update
UA="mon-serveur-minecraft/1.0 (https://votre-domaine.com)"
API="https://hangar.papermc.io/api/v1/projects/Chunky/versions?limit=1&channel=Release&platform=PAPER"
URL=$(curl -fsSL -H "User-Agent: $UA" "$API" | jq -r '.result[0].downloads.PAPER.downloadUrl')
curl -fLO -H "User-Agent: $UA" "$URL"
exitRedémarrez enfin le serveur :
sudo systemctl restart minecraft.serviceAu démarrage, Paper reconnaît le plugin grâce au nom déclaré dans son fichier, et non grâce au nom du .jar. Il remplace l'ancienne version, garde le nom du nouveau fichier et vide le dossier update.
Mettre à jour Paper
Paper publie souvent des correctifs et recommande de le mettre à jour au moins une fois par semaine. Il déconseille en revanche les mises à jour automatiques, car un conflit avec un plugin peut survenir.
sudo systemctl stop minecraft.service
sudo tar -czf /opt/minecraft/backups/avant-maj-$(date +%F-%H%M).tar.gz -C /opt/minecraft server
sudo -u minecraft /opt/minecraft/paper-update.sh 26.3
sudo systemctl start minecraft.service
sudo journalctl -u minecraft.service -fSurveillez le démarrage : les conflits de plugins y apparaissent.
Adapter la sauvegarde automatique
Le script backup.sh du guide de base archive les dossiers de monde présents sur le serveur. Pour sauvegarder aussi vos plugins, remplacez la ligne for de /opt/minecraft/backup.sh par :
for item in world world_nether world_the_end plugins config server.properties; doRevenir à la sauvegarde
Si la migration se passe mal, restaurez l'archive créée au début. Remplacez le nom du fichier par celui affiché par ls :
sudo systemctl stop minecraft.service
sudo ls -lh /opt/minecraft/backups
sudo mv /opt/minecraft/server /opt/minecraft/server-echec
sudo tar -xzf /opt/minecraft/backups/avant-paper-AAAA-MM-JJ-HHMM.tar.gz -C /opt/minecraft
sudo systemctl start minecraft.serviceLe dossier server-echec peut être supprimé une fois que tout fonctionne de nouveau.
En cas de problème
Commencez toujours par lire le début du journal, où les plugins sont chargés :
sudo journalctl -u minecraft.service -n 200 --no-pager
sudo less /opt/minecraft/server/logs/latest.log« Minecraft 26.1 and newer requires running the server with Java 25 or above »
Le service utilise encore une ancienne version de Java. Vérifiez java --version, puis relancez la commande update-alternatives de la section Installer Java 25. L'erreur UnsupportedClassVersionError a la même cause, y compris lorsqu'elle concerne un plugin.
« Server attempted to load chunk saved with newer version of minecraft! »
Le monde a été enregistré par une version plus récente que celle de Paper installée. Installez la bonne version avec paper-update.sh, ou restaurez votre sauvegarde.
Le script paper-update.sh échoue
curl: (22) … 404: cette version de Minecraft n'existe pas chez Paper, vérifiez le numéroAucun build stable trouvé: la version existe, mais n'a pas encore de build stablesha256sum: WARNING: le téléchargement est corrompu, relancez le script. Votreserver.jarn'a pas été modifié
Un plugin ne se charge pas
Cherchez le nom du plugin dans le journal. Les messages les plus courants sont :
| Message | Cause | Solution |
|---|---|---|
Unknown/missing dependency plugins ou UnknownDependencyException |
Une dépendance manque | Installez le plugin indiqué |
Ambiguous plugin name |
Deux fichiers pour le même plugin | Gardez un seul .jar |
Invalid plugin.yml ou zip END header not found |
Ce n'est pas un plugin Paper, ou le fichier est incomplet | Téléchargez de nouveau le bon fichier |
Unsupported API version |
Le plugin vise une version plus récente que votre serveur | Mettez à jour Paper ou prenez une version compatible du plugin |
AccessDeniedException ou « Permission denied »
Un fichier a été créé avec sudo et n'appartient pas à minecraft. Redonnez-lui le dossier. Le guide de base crée un compte système sans groupe dédié, n'indiquez donc que l'utilisateur :
sudo chown -R minecraft /opt/minecraft/servermc-console ne répond pas
Le service minecraft.service n'est pas démarré: lancez le serveur avecsudo systemctl start minecraft.service- Aucune réponse affichée : le serveur démarre encore ou la commande prend du temps. Attendez la ligne
Done, ou augmentez le délai avecsudo MC_CONSOLE_WAIT=10 mc-console version Socket service minecraft.service already active, refusing: le serveur tournait quand la file a été créée. Arrêtez-le avecsudo systemctl stop minecraft.service, puis démarrez-le de nouveau
Aller plus loin
Votre serveur est prêt à recevoir d'autres plugins :
- Gérer les grades et permissions avec LuckPerms
- Installer et configurer EssentialsX
- Accueillir les joueurs Bedrock avec Geyser et Floodgate
Pour le détail des options de Paper, consultez la documentation officielle.