EN

Game servers

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.

10 min read, updated on 18 November 2026

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-console command 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 sudo privileges
  • 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:

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

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

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

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

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

The service runs /usr/bin/java. If Java 21 is also installed, point this command to Java 25:

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

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

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

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

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

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

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

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

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

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

Start Paper

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

The 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

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

You should get:

  • a line This server is running Paper version 26.3-…
  • Server Plugins (0), since no plugin is installed yet
  • the new bukkit.yml and spigot.yml files and the config folder, along with your world folder

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:

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

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

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

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

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

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

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

Then drop the new version into update. Here is the example for 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://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"
exit

Finally, restart the server:

Terminal
sudo systemctl restart minecraft.service

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

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

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

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

Restore the Backup

If the migration goes wrong, restore the archive created at the beginning. Replace the file name with the one shown by 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-YYYY-MM-DD-HHMM.tar.gz -C /opt/minecraft
sudo systemctl start minecraft.service

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

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"

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 number
  • No stable build found: the version exists but does not have a stable build yet
  • sha256sum: WARNING: the download is corrupted, run the script again. Your server.jar has 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:

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

mc-console does not respond

  • The minecraft.service service is not running: start the server with sudo systemctl start minecraft.service
  • No response displayed: the server is still starting or the command is taking time. Wait for the Done line, or increase the delay with sudo 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 with sudo systemctl stop minecraft.service, then start it again

Going Further

Your server is ready for more plugins:

For details on Paper's options, see the official documentation.