How to Install Plugins on a Minecraft Server (Spigot, Paper, Purpur)

Installing a plugin is a two-minute job when everything matches — and a two-hour debugging session when the versions don't. This is the complete procedure for Spigot, Paper and Purpur, plus the troubleshooting section you'll want bookmarked for the day a plugin refuses to load.

//Before you start: two requirements

• ▪A plugin-capable server. Plugins do not work on a vanilla server .jar or on Forge/Fabric. You need Spigot, Paper or Purpur (if you're unsure of the difference, see plugin vs mod vs datapack). Paper is the usual recommendation: best performance, biggest ecosystem.
• ▪A plugin built for your Minecraft version. A plugin compiled against the 1.21 API can crash on a 1.16 server and vice versa. Check the supported versions where you downloaded it — or, if you generate the plugin yourself, pin the version at creation time.

//The installation, step by step

1. Get the .jar file. From SpigotMC, Modrinth, Hangar, a developer, or an AI generator like Voxen. If it comes in a .zip, extract it — the server wants the .jar itself.
2. Stop the server. Hot-dropping files works with some plugins and corrupts state with others; a clean stop costs you one minute and zero surprises.
3. Copy the .jar into the plugins/ folder in your server root (next to server.properties). On a hosting panel, use its file manager or SFTP — same folder.
4. Start the server and watch the console for the plugin's enable message.
5. Verify with /plugins in-game or in the console: your plugin should be listed in green. Red means it loaded with errors — see below.
6. Configure and reload. Most plugins generate plugins/<Name>/config.yml on first start. Edit it, then restart. (Prefer restarts over /reload — the reload command is a well-known source of ghost bugs.)

A healthy startup looks like this:

[Server thread/INFO]: [CrateMaster] Loading CrateMaster v1.0.0
[Server thread/INFO]: [CrateMaster] Enabling CrateMaster v1.0.0
[Server thread/INFO]: [CrateMaster] Loaded 4 crates from config.
[Server thread/INFO]: Done (3.812s)! For help, type "help"

//Where the plugins folder actually is

"Copy it into plugins/" assumes you know where that folder lives, and that depends on how you're running the server.

• ▪Self-hosted or VPS. It's right next to the server .jar, in the same directory as server.properties and eula.txt. It doesn't exist until the server has started at least once — Bukkit creates it on first boot.
• ▪Hosting panel (Aternos, Shockbyte, Nodecraft, PloudOS and similar). Use the panel's built-in file manager, or connect over FTP/SFTP with a client like FileZilla using the credentials the host gives you. The folder is at the root of your server's file tree, same relative location as above.
• ▪Local test server on your own PC. It's inside whatever folder you launched the server .jar from — check next to the batch/shell script or the .jar itself, not your Downloads folder.

If you don't see a plugins/ folder anywhere, start the server once with no plugins installed, let it fully boot, stop it, and the folder will be there.

//Restart, don't /reload

/reload (and its confirmed form, /reload confirm) looks like a shortcut but it isn't a real restart — it re-reads plugin files while the JVM keeps running. Old plugin instances, scheduled tasks and event listeners from the previous load often stay in memory instead of being cleaned up, because Bukkit was never designed to unload classes safely. The result is memory leaks that grow every time you reload, and "phantom" bugs — duplicate messages, commands firing twice, listeners reacting to events they shouldn't — that look like the plugin's fault but are actually caused by the reload itself.

The correct procedure is stop in the console, followed by a normal restart. Tools like PlugMan can hot-swap individual plugins without a full reload, which is fine while you're actively developing and iterating — but treat it as a dev-only tool. Never rely on /reload or PlugMan on a production server.

//How to tell it actually loaded

Run /plugins (or the shorthand /pl) in-game or from the console. You'll get a list of every plugin, color-coded: green means enabled and running, redmeans it's present but disabled — usually because it threw an exception during startup.

For the full picture, check the console log from the moment the server starts. A plugin that loaded cleanly prints something like [Name] Loading Name vX.Y followed by [Name] Enabling Name vX.Yright after. If you see the "Loading" line but not "Enabling", the plugin crashed during its enable phase — scroll up from there to find the stack trace.

If the plugin doesn't show up in /plugins at all, Bukkit never picked up the .jar: it's in the wrong folder, it's not a valid plugin .jar (missing or malformed plugin.yml, see plugin.yml Explained), or the server hasn't been restarted since you added it.

//The config file appears after the first start

Most plugins don't ship a config — they generate plugins/<Name>/config.yml the first time they enable, using their built-in defaults. You can't edit a config that doesn't exist yet, so start the server once, let the plugin create it, then stop the server before editing.

YAML is indentation-sensitive and uses spaces only — never tabs. A tab character or a mismatched indent level is the single most common way to break a config, and it fails loudly: the plugin throws a YAML parsing error at startup and falls back to defaults, or doesn't enable at all.

# correct: two-space indentation, no tabs
economy:
  starting-balance: 500
  currency-symbol: "
quot;

# broken: mixed indentation breaks the parser
economy:
  starting-balance: 500
 currency-symbol: "
quot;

Run the file through any YAML validator before restarting — it takes ten seconds and saves you a round of "why won't my config load" debugging.

//Troubleshooting: the five classic failures

1. "Unsupported API version"

The plugin targets a newer Minecraft than your server runs (e.g. api-version: 1.21 on a 1.20 server). Fix: get a build for your version, update your server, or regenerate the plugin targeting your actual version.

2. UnsupportedClassVersionError

That's Java, not Minecraft: the plugin was compiled with a newer JDK than your server uses. Minecraft 1.20.5 to 1.21.x wants Java 21, and 26.1 and newer want Java 25. If your host lets you pick the Java version, pick the newest. The full table is in the Java version guide.

3. Plugin is red in /plugins, or missing entirely

• ▪Read the console from the first error line, not the last — the root cause is at the top of the stack trace.
• ▪Missing dependency? Some plugins require another plugin (Vault, ProtocolLib…). Install the dependency first.
• ▪Still in a .zip, or double-named plugin.jar.jar? Windows hides extensions by default — check.

4. It loads, but commands don't work

Almost always permissions. Test as OP first: if it works as OP and not otherwise, grant the plugin's permission nodes through your permissions plugin (LuckPerms being the standard choice).

5. Two plugins fighting over the same command

If two installed plugins both register a command with the same name (say, /warp), Bukkit doesn't error out — it silently hands the command to whichever plugin loaded first, based on the load order in plugins/. The other plugin's command still exists, it's just unreachable under its plain name, which looks like a bug when it's actually a naming collision.

You can always reach the shadowed command with its plugin prefix: /nomeplugin:comando (for example /warps:warp) always routes to that specific plugin, regardless of load order. To make the prefix-free version point to the plugin you actually want, edit commands.yml in your server root and set an alias or an override for that command to the correct plugin.