How to Install and Update Plugins on a Paper Minecraft Server
Switch your vanilla Minecraft server to Paper without losing your world, then install and update plugins on a Linux VPS or dedicated server.
On this page
Your values
Enter them once and the commands in this guide update.
The official (vanilla) Minecraft server does not load plugins. This guide explains how to replace it with Paper while keeping your world, then how to install and update plugins cleanly.
It follows on from the Create a Minecraft Server guide and reuses its components: the minecraft user, the /opt/minecraft/server folder, the server.jar file and the minecraft.service service.
By the end of this guide, you will have:
- Java 25 and Paper in place of the vanilla server, with your world intact
- an
mc-consolecommand to talk to the console of the server started by systemd - a first plugin installed and a safe update method
Prerequisites
- A server installed with the Create a Minecraft Server guide
- SSH access with a user that has
sudoprivileges - Enough disk space for a full copy of the server folder
Check Your Current Server
First, check which Minecraft version is running and whether the server already runs 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 VanillaIf the second command displays Paper, your server has already been migrated: back it up, then go straight to enabling the console.
Stop and Back Up the Server
Stop the server, check the available space, then create a full archive:
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/backupsIf you run the server in screen, type stop in its console instead of running the first command.
Install Java 25
Paper recommends Amazon Corretto, available for Debian and Ubuntu. Add its repository, then install 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 libxrender1The service runs /usr/bin/java. If Java 21 is also installed, point this command to Java 25:
sudo update-alternatives --set java "$(update-alternatives --list java | grep -m1 'java-25')"
java --versionThe output must start with openjdk 25.
Switch to Paper Without Losing Your World
The switch consists of replacing server.jar with the Paper file. Since the name stays the same, the systemd service does not need to change, and your world folder, server.properties and player lists stay in place.
Create a script that downloads the latest stable build, verifies its checksum and replaces server.jar. You will reuse it for every update:
sudo nano /opt/minecraft/paper-update.sh#!/bin/bash
# Downloads the latest stable Paper build and replaces server.jar
set -euo pipefail
MC_VERSION="${1:?Specify the Minecraft version, for example 26.3}"
UA="mon-serveur-minecraft/1.0 (https://your-domain.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 "No stable build found for 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'), is in place."On the UA line, replace your-domain.com with your website address or a way to contact you: the Paper API requires a User-Agent that identifies your project and includes contact information.
Make the script executable, then run it as the minecraft user:
sudo chmod 755 /opt/minecraft/paper-update.sh
sudo -u minecraft /opt/minecraft/paper-update.sh 26.3The line server.jar.new: OK confirms that the downloaded file is intact. The old server is kept as server.jar.old.
Enable the Service Console
The service from the base guide contains StandardInput=null, so it has no console, yet many plugins are configured through commands. You will give it one using a named pipe, without opening a network port.
Create the unit that holds the pipe:
sudo nano /etc/systemd/system/minecraft.socket[Unit]
Description=Minecraft Server Console
PartOf=minecraft.service
[Socket]
ListenFIFO=/run/minecraft.stdin
SocketMode=0600Only root can write to this pipe, hence the sudo in front of mc-console.
Next, add a drop-in to the service. This file is added to minecraft.service without modifying it:
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 prevents the service from showing as failed after a normal stop, and TimeoutStopSec gives the server three minutes to save the world.
Finally, create the mc-console command, which sends a command to the server and displays its response:
sudo nano /usr/local/bin/mc-console#!/bin/bash
# Sends a command to the Minecraft console and displays the response from the logs
if [ "$#" -eq 0 ]; then
echo "Usage: mc-console <command>" >&2
exit 1
fi
if ! systemctl is-active --quiet minecraft.service; then
echo "The minecraft.service service is not running." >&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-reloadStart Paper
sudo systemctl start minecraft.service
sudo journalctl -u minecraft.service -fThe first startup takes longer: Paper downloads the Minecraft files, then converts the world. It displays World storage migration is required during startup and waits 30 seconds before continuing, which gives you time to interrupt startup if you do not have a backup.
The server is ready when the line Done (…)! For help, type "help" appears. Exit the log view with Ctrl+C: the server keeps running.
Verify the Result
sudo mc-console version
sudo mc-console plugins
sudo ls /opt/minecraft/server /opt/minecraft/server/worldYou should get:
- a line
This server is running Paper version 26.3-… Server Plugins (0), since no plugin is installed yet- the new
bukkit.ymlandspigot.ymlfiles and theconfigfolder, along with yourworldfolder
The plugins/spark and plugins/bStats folders are created by Paper itself: this is normal. Finally, connect to the server with your Minecraft client and check that your builds are still there.
Install a Plugin
Choose a Compatible Plugin
Before downloading a plugin, check three things on its page:
- it is made for Paper (or Spigot/Bukkit), not Fabric or Forge, which are mods
- it states support for your Minecraft version
- any dependencies are listed, as they must be installed too
Only download from trusted sources: Hangar, Paper's plugin repository, Modrinth, or the project's official website and GitHub repository. A plugin runs with the privileges of the minecraft user and can read the entire server folder.
Install from Hangar
The example below installs Chunky, a world pre-generation plugin. Start by checking its latest version and the supported Minecraft versions:
sudo -u minecraft bash
cd /opt/minecraft/server/plugins
UA="mon-serveur-minecraft/1.0 (https://your-domain.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}'If your Minecraft version is in the list, download the file and exit the minecraft session:
URL=$(curl -fsSL -H "User-Agent: $UA" "$API" | jq -r '.result[0].downloads.PAPER.downloadUrl')
curl -fLO -H "User-Agent: $UA" "$URL"
ls -l
exitIf the URL is null, the plugin is hosted elsewhere: follow the link shown on its Hangar page.
Install from Your Computer
Upload the .jar file to the server, then place it in the plugins folder with the correct owner:
scp MonPlugin.jar YOUR_USER@SERVER_IP:/tmp/sudo install -o minecraft -m 644 /tmp/MonPlugin.jar /opt/minecraft/server/plugins/The file must be directly inside plugins: Paper does not read subfolders. If the download is a .zip archive, extract it and keep the .jar intended for Paper or Bukkit.
Load the Plugin
Restart the server, wait for the Done line, then list the plugins:
sudo systemctl restart minecraft.service
sudo journalctl -u minecraft.service -fsudo mc-console pluginsA loaded plugin appears in green in-game with /plugins. In the logs, it is listed with no error message at startup.
Its configuration is then located in /opt/minecraft/server/plugins/<PluginName>/. Edit it as the minecraft user, then restart the server or use the plugin's own reload command.
Update Plugins
Paper can replace plugins at startup using the plugins/update folder, so you do not have to delete anything by hand.
First, back up the plugins and their configuration:
sudo tar -czf /opt/minecraft/backups/plugins-$(date +%F-%H%M).tar.gz -C /opt/minecraft/server pluginsThen drop the new version into update. Here is the example for 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://your-domain.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"
exitFinally, restart the server:
sudo systemctl restart minecraft.serviceAt startup, Paper identifies the plugin by the name declared in its file, not by the name of the .jar. It replaces the old version, keeps the new file's name and empties the update folder.
Update Paper
Paper frequently publishes fixes and recommends updating at least once a week. However, it advises against automatic updates, as a conflict with a plugin can occur.
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 -fWatch the startup: plugin conflicts show up there.
Adapt the Automatic Backup
The backup.sh script from the base guide archives the world folders present on the server. To back up your plugins as well, replace the for line in /opt/minecraft/backup.sh with:
for item in world world_nether world_the_end plugins config server.properties; doRestore the Backup
If the migration goes wrong, restore the archive created at the beginning. Replace the file name with the one shown by 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-YYYY-MM-DD-HHMM.tar.gz -C /opt/minecraft
sudo systemctl start minecraft.serviceThe server-echec folder can be deleted once everything is working again.
Troubleshooting
Always start by reading the beginning of the logs, where plugins are loaded:
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"
The service is still using an old version of Java. Check java --version, then run the update-alternatives command from the Install Java 25 section again. The UnsupportedClassVersionError error has the same cause, including when it concerns a plugin.
"Server attempted to load chunk saved with newer version of minecraft!"
The world was saved by a newer version than the installed Paper version. Install the correct version with paper-update.sh, or restore your backup.
The paper-update.sh script fails
curl: (22) … 404: this Minecraft version does not exist at Paper, check the numberNo stable build found: the version exists but does not have a stable build yetsha256sum: WARNING: the download is corrupted, run the script again. Yourserver.jarhas not been modified
A plugin does not load
Search for the plugin's name in the logs. The most common messages are:
| Message | Cause | Solution |
|---|---|---|
Unknown/missing dependency plugins or UnknownDependencyException |
A dependency is missing | Install the plugin indicated |
Ambiguous plugin name |
Two files for the same plugin | Keep only one .jar |
Invalid plugin.yml or zip END header not found |
Not a Paper plugin, or the file is incomplete | Download the correct file again |
Unsupported API version |
The plugin targets a newer version than your server | Update Paper or get a compatible version of the plugin |
AccessDeniedException or "Permission denied"
A file was created with sudo and does not belong to minecraft. Give the folder back to it. The base guide creates a system account without a dedicated group, so specify only the user:
sudo chown -R minecraft /opt/minecraft/servermc-console does not respond
The minecraft.service service is not running: start the server withsudo systemctl start minecraft.service- No response displayed: the server is still starting or the command is taking time. Wait for the
Doneline, or increase the delay withsudo MC_CONSOLE_WAIT=10 mc-console version Socket service minecraft.service already active, refusing: the server was running when the pipe was created. Stop it withsudo systemctl stop minecraft.service, then start it again
Going Further
Your server is ready for more plugins:
- Manage Ranks and Permissions with LuckPerms
- Install and Configure EssentialsX
- Welcome Bedrock Players with Geyser and Floodgate
For details on Paper's options, see the official documentation.