Install and Update Paper Plugins with Docker Compose

Choose one owner for each plugin JAR

Paper plugins execute with unrestricted access to the server process and its files. Install only software you trust, then make one workflow responsible for each JAR.

For an itzg/minecraft-server Compose deployment, two practical options are:

• curated local JARs: mount a source folder at /plugins
• declarative Modrinth projects: list projects in MODRINTH_PROJECTS

Do not manage the same plugin with both methods. Duplicate versions commonly make Paper disable the plugin.

Prerequisites

• TYPE: PAPER in the mc service
• a pinned Minecraft/Paper version
• a backup of worlds, configs, plugin data, and plugin JARs
• a trusted plugin release compatible with your Minecraft version

If you have not chosen the server ecosystem yet, compare Paper, Vanilla, Fabric, Forge, and NeoForge.

Option A: synchronize a curated plugin folder

Create a plugins-source directory beside compose.yml, place the trusted JARs there, and mount it read-only:

services:
  mc:
    image: itzg/minecraft-server:java25
    restart: unless-stopped
    ports:
      - "25565:25565"
    environment:
      EULA: "TRUE"
      TYPE: PAPER
      VERSION: "26.1.2"
    volumes:
      - ./data:/data
      - ./plugins-source:/plugins:ro

The image synchronizes /plugins into /data/plugins for plugin-capable server types. The destination remains writable so plugins can create their configuration and data directories.

Before adding a JAR, confirm that it is really a Paper/Bukkit plugin, not a mod or an HTML error page:

file plugins-source/*.jar
sha256sum plugins-source/*.jar
docker compose config

Record the source URL, release version, and checksum in your operator notes.

Option B: manage plugins through Modrinth

The image can resolve compatible plugin releases according to TYPE and VERSION:

services:
  mc:
    image: itzg/minecraft-server:java25
    restart: unless-stopped
    ports:
      - "25565:25565"
    environment:
      EULA: "TRUE"
      TYPE: PAPER
      VERSION: "26.1.2"
      MODRINTH_PROJECTS: |
        luckperms:v5.5.53-bukkit
    volumes:
      - ./data:/data

This example pins the tested Bukkit build of LuckPerms 5.5.53 by version number. A version ID is also supported, but it overrides the image's Minecraft and loader compatibility checks. Confirm compatibility yourself before using one. An unpinned slug follows the latest compatible release and can change on a later container start.

This method can also clean downloads removed from the list. Keep manually managed JARs separate so the ownership boundary stays obvious.

Install or update safely

1. Read the plugin's release notes and dependencies.
2. Trigger a backup and verify it completed.
3. Stop the server before replacing a local source JAR or changing a pinned Modrinth version.
4. Ensure only one version of the plugin remains.
5. Recreate the service and inspect startup.

docker compose stop mc
docker compose config
docker compose up -d mc
docker compose logs -f mc

Do not use /reload as a substitute for a restart. Plugin lifecycles and dependencies are safest to validate during a clean startup.

Validate the plugin

After the server is ready:

docker compose exec mc rcon-cli plugins
docker compose exec mc sh -c 'find /data/plugins -maxdepth 1 -type f -name "*.jar" -print'
docker compose logs --since=10m mc

Paper documents that an enabled plugin appears in green in the plugins output. Also exercise one real plugin feature and check data/logs/latest.log for dependency or load errors.

Roll back a failed plugin change

Stop the service, restore the previous JAR or Modrinth reference and its matching plugin data, then restart. A plugin configuration may have been migrated by the new release, so restoring only the JAR is not always enough.

Use the broader Minecraft Docker update and rollback runbook when the plugin change accompanies a server update.

Troubleshooting

Next steps

• Before changing Paper itself, follow the safe update and rollback runbook.
• Profile a plugin-related slowdown with spark on Paper and Docker.
• For a complete modpack rather than plugins, use the Modrinth Docker guide.