How to Install Plugins on a Paper Minecraft Server

Confirm that the file belongs on Paper

Paper can load Bukkit-style plugins and Paper plugins, but it does not turn every Minecraft extension into a plugin. A Paper plugin normally arrives as a .jar file built for Bukkit, Spigot or Paper. A Forge, NeoForge or Fabric mod is made for a different loader and will not run just because it is placed in Paper's plugins directory. A proxy plugin built only for Velocity or BungeeCord belongs on that proxy, not on a backend Paper server.

Start by recording the server's exact Minecraft and Paper versions with the version command or the startup log. Then read the plugin's supported game versions, platform requirements and dependency list on its official release page. Do not rely only on a filename or a comment saying that a release “should work.” A plugin can be valid Java software and still target an incompatible server API or a newer Java runtime.

Paper's documentation says Bukkit and Paper plugins can communicate and depend on one another once enabled, but Paper-only plugins need Paper's plugin loader. If a download offers several files, choose the one explicitly labelled for Paper or Bukkit rather than Fabric, Forge, Velocity or a developer API. Some projects distribute a zip containing multiple platform JARs; extract it offline and upload only the correct server plugin.

Treat every plugin as trusted server code

A plugin is not a harmless data pack. Paper warns that plugins receive full and unrestricted access to the server and the machine running it. A malicious or compromised JAR can read files available to the server account, alter worlds and plugin data, make network requests or consume resources. Install the smallest plugin set that solves a real need, and give each new JAR the same scrutiny you would give any production dependency.

Prefer the author's listing on Paper's Hangar repository, Modrinth, BukkitDev or the project's official GitHub releases, which are the sources Paper points administrators toward. Confirm that the project identity, author links and documentation agree across pages. Avoid re-upload sites, shortened download links and similarly named clones. Never run an executable installer to obtain a server plugin, and do not upload a web page accidentally saved with a .jar extension.

Record the download URL, release version and publication date in a small change note. If the author publishes a SHA-256 checksum or a signed release, verify it after download and again after upload. A checksum proves that the bytes match the publisher's stated artifact; it does not prove that the publisher or code is trustworthy. Also review recent release notes and unresolved security advisories before choosing the build.

• Download from a project-controlled page and verify the author and platform.
• Match the plugin release to the server's Minecraft, Paper and Java versions.
• Read required dependencies, configuration changes and upgrade notes first.
• Keep the exact source URL, version and checksum when one is available.

Back up and stage the change

Stop the production server cleanly and make a restorable backup before the first installation. Include all world folders, server configuration, the entire plugins directory and any external database used by plugins. Paper's troubleshooting guide explicitly warns that modifying server files while it is running can corrupt them. Store the backup outside the live directory, label it with the date and current versions, and confirm that the archive contains the files you expect.

For an established server, restore that backup into an isolated staging directory. Match the production Paper build, Java runtime, startup flags and existing plugin versions. Use another port, block player access and disconnect outgoing integrations or production databases. Staging is especially important for permissions, claims, economy, inventory, world-editing and protocol plugins because their first startup may create configuration, migrate data or depend on another plugin.

Add one logical change at a time. If the plugin requires a library such as a permissions or protocol provider, install the documented dependency with it, but do not mix unrelated plugin updates into the same test. A small change set makes startup errors attributable and rollback predictable. The full server-upgrade backup procedure at /blog/update-paper-minecraft-server-safely also applies when a plugin replacement can migrate valuable data.

Install the JAR with the server stopped

Locate the plugins folder in the Paper server's working directory, normally beside the Paper server JAR. With the server fully stopped, upload the chosen .jar into the root of that folder using the host's file manager or SFTP. Paper does not search subdirectories for plugin JARs, so a tidy plugins/new directory will silently prevent loading. If the project supplied a zip, extract it on your computer and follow its documentation rather than placing the zip on the server.

Make sure only one JAR for that plugin is active. Keeping Plugin-1.2.jar and Plugin-1.3.jar together can produce an ambiguous plugin-name error; preserve the old JAR in the offline backup instead. Do not rename a different mod or an HTML error response to end in .jar. A correct extension is necessary, but the file must also contain a valid plugin description understood by Paper.

Start the server normally and let the whole initialization sequence finish. Do not use Bukkit's reload command to install or update plugins: Paper marks it deprecated and recommends a restart because reload is known to cause plugin issues. On a busy server, keep it closed to players until startup and acceptance checks pass. A process reaching the “Done” line only means startup completed, not that every plugin enabled successfully.

• Shut down fully and verify the Java process has exited.
• Place the correct .jar directly in plugins, never in a nested folder.
• Remove duplicate versions from the active directory.
• Perform a full start and keep players out until verification is complete.

Verify loading before trusting the plugin

Read the startup console from the beginning, then inspect logs/latest.log. Paper recommends the plugins command in console or /plugins in game: a green entry indicates that no problem occurred while enabling it, while red means it failed to load or was disabled. The version command for the plugin provides another quick identity check. Save the startup log with the change note so you can compare later failures with the first known-good boot.

Loading is only the first gate. Open the generated configuration and compare it with the plugin's current documentation before changing defaults. Test the smallest user journey the plugin exists to support, including a normal player without operator privileges. Check commands, permissions, stored data, restart persistence and interactions with related plugins. Restart staging a second time to prove that created data and configuration can be read again.

Watch the console during the test for warnings and exceptions, and confirm that scheduled backups still complete. For plugins that touch worlds or inventories, verify representative existing chunks and player records. For chat, webhooks or databases, confirm that messages and writes go only to the intended destination. If the plugin adds noticeable tick work, compare a representative spark profile with the baseline described in /blog/minecraft-server-lag-fix-guide instead of judging from one quiet minute.

Fix the common plugin loading failures

An UnknownDependencyException names a required plugin that is missing. Return to the plugin's official documentation, install the supported dependency, and keep dependent plugins together during tests. Do not download the first similarly named JAR from a search result. Library plugins may expose few visible features but still need the correct version for every plugin that relies on them.

An InvalidDescriptionException mentioning plugin.yml usually means the file is not a valid Paper plugin, is for a mod loader, is the wrong artifact from a multi-platform zip, or was damaged during download or transfer. Download it again from the official page, compare the size or checksum, and use SFTP or the hosting panel. If Paper logs an ambiguous name, remove the duplicate JAR. If it reports cyclic loading, send the complete error to the involved authors rather than enabling legacy loading as a casual fix.

When startup succeeds but a new problem appears, stop the server and retest without the new plugin. For a conflict among many plugins, Paper recommends a binary search: split the suspect set into two groups, keep dependencies with their dependants, enable one group, and repeat with the failing half. Change files only while stopped. Preserve each log, exact plugin list and reproduction step so the plugin author receives useful evidence rather than a screenshot of the last line.

Deploy, monitor and roll back cleanly

Repeat the tested installation during a maintenance window: stop production, take the final consistent backup, upload the exact staged JAR set, start, inspect the full log and run the same acceptance checklist. Reopen access only after the required plugin is green and core player actions still work. Monitor errors, tick time, memory and plugin-specific data through a real period of player activity, not just an empty-server boot.

Define rollback triggers in advance, such as a required integration failing, player data changing incorrectly, repeat crashes or sustained performance regression. If one occurs, stop the server and preserve the failed run's logs. Restore the entire matching pre-install state, including plugin JARs, configuration, plugin data, worlds when changed, and the corresponding external database snapshot. Removing only the new JAR may be insufficient after it has written data or changed another plugin's files.

Keep a short inventory of active plugins, versions, official source pages, dependencies and the last successful test date. Review it before Minecraft or Paper upgrades and remove plugins that no longer justify their access or maintenance cost. More focused server operations guides are available at /blog, and /pricing shows hosting options when a verified workload—not an untested plugin—demonstrates that the server needs more capacity.