How to Install Paper Plugins: A 2026 Guide

Installing a Paper plugin is supposed to be a 30-second job: drop the jar, restart, done. In practice, a quarter of new server admins lose an afternoon to silent failures, mismatched versions, or directory confusion. This guide walks through the correct install flow and then explains every common error in plain English so you can fix it without grepping forum posts from 2017.

We're targeting Paper 1.20.x and newer here. Older builds work the same way, but a couple of folder paths have moved over the years - if you're on 1.17 or earlier, double-check the section on plugins/ location below.

What you need before you start

Before touching anything, confirm three things:

1. You have shell or file-manager access to the server's root directory. Game-panel-only access (where you can only edit server.properties and restart) is not enough - you need to upload a .jar to /plugins/.
2. The plugin's .jar matches your server's Minecraft version range. Most plugins list compatibility in the description ("Supports 1.20.4 - 1.21.4"). Mismatches are the #1 cause of "could not load" errors.
3. The plugin targets Paper (or its parent Spigot/Bukkit). Mods (Fabric, Forge, NeoForge) are a different ecosystem - they won't load on Paper at all and will throw cryptic errors on startup.

The install flow (the happy path)

This is the entire correct sequence. Five steps:

1. Stop the server fully. Not restart - stop. A hot drop sometimes works but breaks plugins that register listeners at boot.
2. Upload the .jar to <server-root>/plugins/. Just the .jar file. Don't unzip it. Don't put it in a subdirectory. Don't rename it.
3. Start the server. Watch the console output.
4. Look for the load line. You're hoping for something like [12:34:56] [Server thread/INFO]: [PluginName] Loading PluginName vX.Y.Z.
5. Type pl in the console. Server responds with a list of loaded plugins. Yours should appear in green. Red means it loaded but failed to enable. Strikethrough means it tried to load and crashed.

That's it. If your plugin appears in green, you're done - jump straight to the configuration section of the plugin's README to actually use it.

If it didn't load cleanly, keep reading.

"Could not load 'plugins/xxx.jar'" - what it actually means

This single error message hides at least four distinct problems. Read the stack trace right after it - the second or third line tells you which one you hit.

Wrong Minecraft version

The line you'll see: org.bukkit.plugin.InvalidPluginException: ... unsupported API version 1.21

The plugin was built against a newer Paper API than your server is running. Either upgrade your server or downgrade the plugin to an older release that matches. The latter is usually faster - most plugins keep download archives for older versions.

Missing dependency

The line you'll see: Unknown dependency: Vault. Please download and install ... to run this plugin.

The plugin depends on another plugin you don't have installed. Look up the named dependency (often Vault, ProtocolLib, WorldEdit, or PlaceholderAPI), drop it into plugins/, and restart. The order doesn't matter - Paper resolves dependencies before enabling anything.

Plugin built for the wrong platform

The line you'll see: java.lang.NoClassDefFoundError: net/minecraft/server/... or Cannot find main class

You downloaded a Fabric mod or a Forge mod by mistake. Re-download from the plugin's actual Paper/Spigot release page. If the project only ships mods (not plugins), there's no fix - you'll need to find a Paper-native alternative.

Java version mismatch

The line you'll see: UnsupportedClassVersionError: ... has been compiled by a more recent version of the Java Runtime

Your server is running an older Java than the plugin requires. Paper 1.20.5+ needs Java 21. Paper 1.18-1.20.4 needs Java 17. Older runtimes will refuse to load newer plugins. Upgrade Java on the server (most game panels expose this in a dropdown).

Where the plugins/ folder actually lives

The exact location depends on how you host:

If you have multiple worlds or use a bungeecord/velocity proxy in front, each backend server has its own plugins/ directory. The proxy has a separate one (plugins/ next to velocity.jar or bungeecord.jar) that only loads proxy-side plugins. Proxy plugins do not load on backend servers and vice versa.

Configuring after install

Most plugins generate their config the first time they run. Look in plugins/<PluginName>/ - you'll see a config.yml. Stop the server before editing. Don't edit while the server is running unless the plugin explicitly supports hot reloads.

Some gotchas:

• YAML is whitespace-sensitive. Two-space indents, no tabs. A single tab can break the whole file silently and the plugin will fall back to defaults without telling you.
• Comments use # at the start of the line. Inline value # comment works too, but it's the safest place for typos.
• String values with special characters need quotes. Specifically anything containing :, #, &, or starting with *. prefix: "&8[&aMyServer&8]" not prefix: &8[&aMyServer&8].

After editing, restart the server (not just /reload - that's deprecated and causes more problems than it solves on modern Paper).

Updating a plugin

There's no "update" in the Paper sense - you just replace the old .jar with the new one:

1. Stop the server.
2. Delete the old .jar from /plugins/.
3. Drop the new .jar in the same directory.
4. Start the server.
5. Check the plugin's changelog for config migration notes. Major version bumps sometimes require manual edits to config.yml - the plugin will usually warn you in the console if so.

Don't try to merge old and new config.yml files by hand. Either let the plugin regenerate (you lose customizations) or apply the changelog's migration instructions carefully.

Removing a plugin

Stop server → delete .jar from /plugins/ → start server.

If you also want the plugin's config and data wiped, delete the plugins/<PluginName>/ directory too. Be careful - some plugins store player data here (economy balances, claims, kits). Always back up the directory before deleting if there's any chance you'll want to reinstall later.

Performance check after a new plugin

Every plugin you add costs main-thread time. After installing anything non-trivial, run spark for 5 minutes during normal play and check the top entries. If your new plugin is in the top 5 and you didn't expect it to be, dig into its config - many plugins have aggressive defaults (check intervals, particle effects, world scans) that you can tune down.

We covered the full TPS troubleshooting flow in a separate post: Optimizing Paper Server TPS. Worth reading after every install batch.

Where to get plugins

The trust pyramid, roughly:

• Official author distribution (the developer's own site, GitHub releases, Modrinth) - safest, you know it's the real binary
• Reputable marketplaces (Modrinth, Hangar, Polymart, BuiltByBit) - vetted-ish, occasionally re-uploaded versions
• SpigotMC resource forum - large catalog, variable quality, no formal review
• Random Discord servers, leak sites, "cracked" jars - never. Backdoored builds are common.

If you need something the marketplaces don't have - or you need it built and supported by one person rather than abandoned in 2022 - we build production-grade Paper plugins on demand. See our custom plugin development service for what that looks like.

TL;DR

1. Stop server
2. Drop .jar in /plugins/
3. Start server
4. Type pl and confirm it's green
5. Read the plugin's README for actual config

90% of installs really are that fast. The other 10% are version mismatches or missing dependencies, both fixable in five minutes once you can read the error message.

Stuck on an install we didn't cover here? Hop into our Discord - we usually answer fast.