Plugins, mods and what Paper can run
Paper runs plugins written for Bukkit, Spigot and Paper. They live entirely on the server, so your players join with the normal game and nothing to download. That is the big practical difference from mods, which change the game itself and usually have to be installed on every player's client at the same version.
Fabric, Forge and NeoForge mods are not plugins, even though they are also .jar files. Drop one into the plugins folder and Paper reports an invalid plugin.yml, because the jar does not carry the file a plugin needs. If what you want only exists as a mod, our guide to Paper, Forge and Fabric explains the switch.
You may also see the term Paper plugin. Those use a paper-plugin.yml file instead of, or as well as, the classic plugin.yml. For a server owner nothing changes: they install the same way, into the same folder.
- Bukkit, Spigot and Paper plugins: go in plugins, server only
- Fabric, Forge and NeoForge mods: not plugins, and Paper will not load them
- Players need nothing extra to join a plugin server
Where to download plugins, and what to check first
PaperMC's documentation recommends Hangar, its own plugin repository, as the first place to look, and also lists Modrinth, BukkitDev and GitHub. It opens with a warning worth repeating: only install plugins from sources you fully trust, because a plugin gets unrestricted access to your server and the machine it runs on. A plugin is code you are choosing to run, so prefer projects with a public history, a visible author and recent updates.
Before you download, check that the plugin supports your Minecraft version. Run version in the console to see exactly what your server runs, then pick the plugin file built for it. Hangar and Modrinth show the supported versions on every release. Some plugins also depend on another plugin to work, and their page says so. Install those at the same time.
The file you upload must end in .jar. If the download is a .zip, extract it and look for the jar labelled for your platform, often marked bukkit or paper.
- Hangar first, then Modrinth, BukkitDev or the author's GitHub
- Match the plugin release to the version shown by the version command
- Install any listed dependency alongside it
- Upload the .jar, never the .zip it came in
Install a plugin, step by step
Every Paper server has a plugins folder in its main directory, created on the first start. That folder is the only place Paper looks. On a hosted server you reach it through the panel's file manager or over SFTP; how game server hosting works explains both if they are new to you.
Paper's own steps end with a restart, and that is the step to follow. The reload command is deprecated for removal in Paper's command reference, which says it is known for causing issues with plugins and recommends restarting instead. A full stop and start loads every plugin from scratch.
- Download the plugin jar for your server's version
- Open the plugins folder in the server's main directory
- Upload the jar straight into plugins, not into a subfolder
- Restart the server
- Run plugins in the console, or /plugins in game, and look for a green name
Check it loaded, then configure it
The plugins command lists every plugin the server found. Green means enabled. Red means it failed to load or was disabled, and the startup log explains why. A yellow star in front of a name marks a plugin that loaded through Paper's legacy support.
Most plugins create their own folder inside plugins on the first start, named after the plugin, holding a config.yml and any data files. Edit those with the server stopped and start it again afterwards, or check the plugin's documentation for its own reload command.
Commands that a plugin adds are usually locked behind permissions. In a plugin's plugin.yml, a permission with no default set falls back to op, which is why operators can use new commands straight away and other players cannot. To hand out specific commands to specific players, use a permissions plugin such as LuckPerms instead of giving everyone operator status.
- Green: enabled and running
- Red: failed or disabled, read logs/latest.log
- Yellow star: loaded through legacy support
- Settings: plugins/<PluginName>/config.yml in most plugins
When a plugin is red or missing
Open logs/latest.log and look near the start, where the server loads plugins. Paper's documentation lists the messages you are most likely to meet, and each one has a direct fix. Read the first line or two of any error rather than the whole stack trace; that is where the plugin says what went wrong.
If the log does not mention your plugin at all, the server never saw it. Paper only scans the root of the plugins folder, so a jar in a subfolder is ignored, and only files ending in .jar count.
- Missing dependency: the log names the plugin it needs, such as Vault. Install it and restart
- Invalid plugin.yml: not a Paper plugin. It may be a Fabric or Forge mod, a broken download, or a file damaged by a non-binary FTP transfer
- Ambiguous plugin name: two versions of the same plugin are installed. Keep one and restart
- Nothing in the log: move the jar to the root of plugins and check it ends in .jar
Update and remove plugins without breaking anything
Never swap a jar while the server is running. Paper's update guide gives a cleaner route: create a folder named update inside plugins, put the new plugin jars there, and restart. The server picks them up on the way back, and you can update Paper itself in the same restart. Take a backup first, including the plugin config folders, so a bad release is a quick restore rather than a rebuild.
To remove a plugin, stop the server, delete its jar from plugins and start again. Its config folder stays behind until you delete it, which is handy if you change your mind.
Each plugin adds memory and some work to every tick. A normal plugin list sits well within a 4 GB server, and the Minecraft RAM calculator gives you a figure for your own setup. If the server starts to feel slow after an install, the lag and low TPS guide shows how spark names the plugin responsible. And when no existing plugin does exactly what you want, you can commission a custom plugin built for your server.
- Update: new jar into plugins/update, then restart
- Remove: stop, delete the jar, start
- Back up plugin configs along with the world