FR

Serveurs de jeux

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.

11 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.

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-console pour 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 :

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

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

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

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

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

Le service lance /usr/bin/java. Si Java 21 est aussi installé, faites pointer cette commande vers Java 25 :

Terminal
sudo update-alternatives --set java "$(update-alternatives --list java | grep -m1 'java-25')"
java --version

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

Terminal
sudo nano /opt/minecraft/paper-update.sh
Terminal
#!/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 :

Terminal
sudo chmod 755 /opt/minecraft/paper-update.sh
sudo -u minecraft /opt/minecraft/paper-update.sh 26.3

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

Terminal
sudo nano /etc/systemd/system/minecraft.socket
Configuration
[Unit]
Description=Console du serveur Minecraft
PartOf=minecraft.service

[Socket]
ListenFIFO=/run/minecraft.stdin
SocketMode=0600

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

Terminal
sudo mkdir -p /etc/systemd/system/minecraft.service.d
sudo nano /etc/systemd/system/minecraft.service.d/console.conf
Configuration
[Unit]
Requires=minecraft.socket
After=minecraft.socket

[Service]
Sockets=minecraft.socket
StandardInput=socket
StandardOutput=journal
StandardError=journal
SuccessExitStatus=130 143
TimeoutStopSec=180

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

Terminal
sudo nano /usr/local/bin/mc-console
Terminal
#!/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 cat
Terminal
sudo chmod 755 /usr/local/bin/mc-console
sudo systemctl daemon-reload

Démarrer Paper

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

Le 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

Terminal
sudo mc-console version
sudo mc-console plugins
sudo ls /opt/minecraft/server /opt/minecraft/server/world

Vous 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.yml et le dossier config, ainsi que votre dossier world

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 :

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

Terminal
URL=$(curl -fsSL -H "User-Agent: $UA" "$API" | jq -r '.result[0].downloads.PAPER.downloadUrl')
curl -fLO -H "User-Agent: $UA" "$URL"
ls -l
exit

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

Terminal
scp MonPlugin.jar VOTRE_USER@IP_SERVEUR:/tmp/
Terminal
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 :

Terminal
sudo systemctl restart minecraft.service
sudo journalctl -u minecraft.service -f
Terminal
sudo mc-console plugins

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

Terminal
sudo tar -czf /opt/minecraft/backups/plugins-$(date +%F-%H%M).tar.gz -C /opt/minecraft/server plugins

Déposez ensuite la nouvelle version dans update. Voici l'exemple de Chunky :

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

Redémarrez enfin le serveur :

Terminal
sudo systemctl restart minecraft.service

Au 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.

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

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

Terminal
for item in world world_nether world_the_end plugins config server.properties; do

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

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

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

Terminal
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éro
  • Aucun build stable trouvé : la version existe, mais n'a pas encore de build stable
  • sha256sum: WARNING : le téléchargement est corrompu, relancez le script. Votre server.jar n'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 :

Terminal
sudo chown -R minecraft /opt/minecraft/server

mc-console ne répond pas

  • Le service minecraft.service n'est pas démarré : lancez le serveur avec sudo 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 avec sudo 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 avec sudo systemctl stop minecraft.service, puis démarrez-le de nouveau

Aller plus loin

Votre serveur est prêt à recevoir d'autres plugins :

Pour le détail des options de Paper, consultez la documentation officielle.