How to Add Plugins to a Paper Server

A Paper plugin is a single .jar file you drop into one folder and load with a full server restart — that's genuinely the whole job, and most of the trouble people hit comes from one of two places: the plugin doesn't match the server's Minecraft version, or they tried to load it with /reload instead of restarting. Get those two things right and installing is a thirty-second task. This assumes you've already got a Paper server running; if you're picking what to install, the must-have plugins for a new server is a better starting point than this one.

One thing to settle up front, because it's the cause of more failed installs than anything else: plugins lag the game. When a new drop ships, the server software and the plugins both have to catch up, and they don't catch up at the same speed.

Check the version before you download anything

Every plugin is compiled against a specific Minecraft API, and a .jar built for the wrong version will either show up red in your plugin list or crash the moment it tries to enable. So the first step isn't downloading — it's knowing exactly what version your server runs, then matching the plugin to it.

As of September 2026, Paper's stable builds are for 26.2 "Chaos Cubed" (shipped 2026-06-16), while its builds for the newer 26.3 "Wilderness Bound" (shipped 2026-09-15) are still experimental. Either way, each plugin still needs its own compatibility check. Use the newest stable Paper build supported by your plugin stack; keep 26.1 when a required plugin has not caught up. You can see which live servers are running each at /servers/version/26.1, /servers/version/26.2 and /servers/version/26.3.

For where to download, Paper's own docs point at three main repositories:

• Hangar — Paper's plugin repository, built by the Paper team. Each release lists its supported Minecraft versions, and it understands ranges (1.19-1.20.2) and wildcards (1.20.x), so you can tell at a glance whether your version is covered.
• Modrinth — same idea, every download is tagged with the versions it supports.
• BukkitDev — the older Bukkit/Spigot listing site, still widely used.

GitHub Releases and a plain web search turn up valid downloads too. Wherever you get it, the rule is the same: confirm the release lists support for your running version before you click download. And only install from a source you trust — a plugin gets full, unrestricted access to your server and to the machine it runs on, so a sketchy .jar is not a small risk.

If the download lands as a .zip instead of a .jar, don't panic — extract it and look inside. Some plugins bundle a config or extra resources alongside the actual .jar. The file Paper loads has to end in .jar.

Drop the .jar into the plugins folder

In your server's root directory — the same folder that holds paper.jar, server.properties, and your worlds — there's a folder called plugins. Put the .jar in there. Locally that's drag-and-drop; on a managed or shared host it's an upload through the web panel's file manager or over SFTP.

The one mistake worth calling out: the file has to sit at the top level of plugins/. Paper does not scan subfolders. If you drop it into plugins/MyPlugin/ or any nested directory, it simply won't be found, and you'll spend ten minutes wondering why a perfectly good plugin never loaded. The .jar goes directly in plugins/, nowhere deeper.

Restart the server — don't use /reload

A full stop and start is the only safe way to load a plugin. Type stop in the console (or hit the restart button on your host's panel), wait for it to come back up, and the plugin loads cleanly on boot. That's it.

What you should not reach for is /reload. It looks like a shortcut, and Paper's docs flag it directly: "The reload command is deprecated for removal. You should instead restart your server if you wish to update your plugins, as the reload is known for causing issues with plugins."

Why /reload actually breaks things

It's worth understanding the reason, because it explains a whole category of weird bugs. /reload disables every plugin and re-enables them, simulating the server shutting down and starting back up while it's still running. The problem is that Java has no safe way to unload code that's already loaded. So the old code and the new code end up coexisting and conflicting — the classic symptom is the "zip file closed" error when a .jar got swapped out underneath a running plugin. Plugins that expect a fresh start end up working with stale data, and something as ordinary as a permission check can quietly start returning the wrong answer afterward. It got worse on newer Java versions, not better. A clean restart sidesteps all of it.

There's a separate command, /paper reload, that only re-reads Paper's own config. It doesn't touch spigot.yml or your plugins' own configs, and it doesn't load or reload plugin code — so it's not the answer for installing anything either.

Find the config and verify with /plugins

The first time a plugin loads successfully, most of them generate their own folder at plugins/<PluginName>/ containing a config.yml and sometimes a few other files. That's where you change settings. Edit the file, save it, and restart again to apply the change — config edits need a restart for the same reason installs do, unless the plugin ships its own reload command like /<plugin> reload.

To confirm everything loaded, run /plugins in-game or type plugins in the console. You'll get a color-coded list:

• Green means the plugin loaded and is running.
• Red means it failed to load or was disabled — go read logs/latest.log for the stack trace. The two most common causes by a wide margin are a version mismatch and a missing dependency, and the log names which one it is.
• A yellow star on a Bukkit plugin means legacy support kicked in because the plugin didn't specify a version — usually harmless, but a sign it's old.

Click a plugin's name in that list to see its version, or run /version <plugin_name> for the same thing. The list also separates "Paper plugins" from "Bukkit plugins." Most Spigot and Bukkit .jars run fine on Paper, but newer Paper-native plugins use a different loader, so don't take it as a guarantee that every Spigot plugin will work — version compatibility still has the final say.

A red plugin caused by a missing dependency is the one people misread as a bad download. Some plugins need a library plugin underneath them — an economy provider, a protocol library — and they go red until you install that dependency too. The log tells you exactly what it couldn't find. Permission and anti-cheat plugins are common culprits here, so if you're wiring up LuckPerms ranks or an anti-cheat, check their pages for required libraries before you assume the .jar is broken.

FAQ

How do I update a plugin without breaking it?

Stop the server, delete the old .jar from plugins/ so two versions can't load at once, drop in the new one, and start back up. Replacing while the server runs is exactly the situation that triggers the "zip file closed" classloader error, so don't do it live. Paper also has an update/ folder that swaps .jars on the next restart, but the mechanics vary by setup — for one plugin, the manual delete-and-replace is simpler and harder to get wrong.

My plugin is green in /plugins but the commands don't work. What's wrong?

That's almost always permissions, not the plugin. The plugin loaded fine, but your account doesn't hold the node its commands check. If you're running a permissions plugin, grant yourself the right node (or operator status for testing) and try again. If there's no permissions plugin at all, make sure you're opped. A green plugin whose commands "do nothing" is a permission gap nine times out of ten.

Can I add a plugin to a server I just play on?

No. Plugins are server-side and only the owner can install them, the same way only the owner can change the server's Minecraft version or add multi-version bridging like ViaVersion. As a player you connect with a normal client on the matching protocol — Java on port 25565, Bedrock on 19132 — and whatever plugins the owner runs are simply part of that server.

I installed a 26.2 plugin and it's red on my 26.1 server. Is the file broken?

Probably not — that's a version mismatch, which is the single most common red entry. A plugin built against the 26.2 API can fail to enable on a 26.1 server, and logs/latest.log will say so. Grab the build flagged for 26.1 instead, or move the server up to 26.2 once the rest of your plugins support it — as of September 2026 that's Paper's stable line, while its 26.3 builds are still experimental.