Short answer
Download the plugin from Hangar, Modrinth or BukkitDev, drop the .jar in the plugins folder, restart, and check /plugins. Green means loaded; red means the startup log says why; a star means it loaded in legacy mode and was built for an older Minecraft version.
Plugins are JAR files in a folder, and most plugin problems are three specific mistakes: a build for the wrong Minecraft version, a dependency that was not installed alongside it, or a configuration file nobody edited. All three announce themselves in the same place, the startup log.
This guide is the install, the colours, and those three failures in the order they occur. It assumes Paper or Purpur: the vanilla server implements no plugin API, so a plugin cannot run there at all.
Before you start
- A Paper or Purpur server
- File access to the plugins folder
- A backup, since plugins write their own configuration files
1. Install the plugin from a repository
Get the JAR from Hangar, Paper's own repository, or from Modrinth or BukkitDev. Paper's documentation is direct about why the source matters: a plugin runs with full and unrestricted access to the server and the machine it runs on, so the JAR is code you are choosing to trust.
Check the page before you download: the Minecraft versions it supports, when it was last updated, and whether it is maintained. A plugin last touched before your version may still load, but the log is where you will find out.
1. Download the .jar (extract it from a .zip if needed)
2. Put the .jar in the plugins/ folder
3. Restart the server
4. Run /plugins and read the colour- The file must end in
.jar. Some plugins ship as.zip, in which case the JAR inside is often named for the platform: bukkit or paper. - Do not unzip a plugin into the plugins folder. The folder takes JARs, not folders of files.
2. Restart and read what /plugins tells you
Restart the server, then run /plugins. Paper colours the list: green means the plugin enabled cleanly and can be assumed working, red means it failed to load or was disabled, and a yellow star means it loaded with legacy support, which usually means it was built for a very old Minecraft version or never declared one.
Nothing in that list says why. The reason is always in the startup log, and reading it is step four.
/plugins
/version <plugin_name>3. Read the startup log for the actual reason
Paper logs every plugin loading, and a failure names itself in the first lines that mention the plugin. Three messages cover almost everything.
Take the excerpt from the log rather than the console, which scrolls: reading logs covers how to work back to the first error.
Could not load plugin X, invalid plugin.yml
-> the JAR is corrupt, incomplete, or not a plugin. Download it again.
NoClassDefFoundError: some/other/Class
-> a dependency is missing. Read the plugin page for its required plugins.
NoSuchMethodError
-> built for another Minecraft version. Take a build for your version.4. Configure it, then verify it works in game
A plugin that loads is not a plugin that is set up. Most write a configuration file into their own folder on first run, and the sensible defaults are often not what your server needs.
Test the actual feature, not the plugin's presence: a permissions plugin is tested by having someone build where they should not, and a backup plugin is tested by restoring from one. Backing up has that test.
plugins/
SomePlugin.jar
SomePlugin/
config.yml the settings you are meant to edit
messages.yml what it says to players, often5. Remove it properly when you are done
To uninstall, stop the server, delete the JAR and its folder, and restart. Deleting only the JAR leaves the configuration behind, which is what you want if you plan to reinstall and what you do not want if you were removing a problem.
Then check the plugin list again. A plugin that leaves a scheduled task or a registered command behind can keep affecting the server until the restart, which is why the restart is part of removing it rather than an extra step.
Good to know
- Install and restart; do not use
/reload. Paper deprecates the plain reload command because plugins frequently misbehave under it, and it can leave the server in a state that only a full restart fixes. - Every plugin costs memory from the moment it loads until the server stops, whether or not anyone is using it. The plugins guide covers keeping the list short.
- Paper plugins and Bukkit plugins live in the same folder. Paper's documentation notes the distinction matters mainly to plugin developers; for an administrator, both load the same way.
- A plugin that works on one Minecraft version can break on the next. Read the startup log after every version upgrade, not only when something is visibly wrong.
Common questions
Where do I put plugin files?
In the plugins folder next to the server JAR, as .jar files. Some plugins ship as .zip, in which case extract it and put the JAR inside. Do not unzip a plugin into the folder.
Can I install plugins on a vanilla server?
No. The vanilla server implements no plugin API. Switch to Paper, which reads your existing world unchanged, and plugins then load normally.
Why is a plugin red in /plugins?
It failed to enable. The startup log names the reason, and it is almost always a corrupt JAR, a missing dependency or a build for another Minecraft version. Find the plugin's name in the log and read the lines after it.
Do I need to restart after installing a plugin?
Yes. Plugins load at startup, and Paper deprecates the reload command because plugins misbehave under it. Restart, then check /plugins.
What does the star next to a plugin mean?
It loaded in legacy mode. That usually means it was built for a very old Minecraft version, or that its author never specified a supported version. It may work, and it is also the first thing to check when a plugin behaves oddly.
Sources
Official documentation this guide was checked against.
Rather not run this on your own machine? PufferHost gives every player a free Minecraft server with 3 GB of RAM and 10 slots. Create a free server.