Installing plugins on a Minecraft server (Paper, Purpur)

Plugins add commands, build protection, an economy, minigames and much more to your server. Players don't need to install anything. This guide covers one-click installation right in the customer area as well as uploading a file by hand, configuring a plugin, updates and fixing the most common errors.

Before you start#

• Plugins only work on Paper, Purpur and Folia. Fabric, Forge and NeoForge use mods instead of plugins and the tab is called Mods, see Mods and modpacks. Vanilla supports neither. The difference is explained in the article Plugins or mods?
• The plugin must support your Minecraft version. A plugin for an older version often won't load or behaves unpredictably.
• Only a minority of plugins work on Folia. The plugin has to state Folia support explicitly.
• A plugin can do anything on the server. The Paper documentation points out that plugins have full, unrestricted access to the server. Only install plugins from trusted sources.

Installing through the customer area#

1. Open My services, click your server and go to the Plugins tab.

2. Click the Browse sub-tab. Without a search, you'll see the most downloaded plugins for your server type and version.

3. In the Source switch, pick a catalog (explained below). Start with Modrinth.

4. Type a name in the “Search plugins” field, for example LuckPerms, and click Search.

5. On the plugin, click Install. If you want a version other than the latest, click Versions first and pick it from the list.

6. Look through the Install … dialog:

   • Main file – the plugin file that gets uploaded to the plugins folder.
   • Required dependencies – other plugins it won't start without. The customer area installs them along with it. Only untick the ones you've already uploaded yourself.
   • Warnings about files with the same name that the install will overwrite, and about plugins the author says it doesn't work with.
   • Download size – the total size.

7. Click Install.

   When it's done, you'll see the message Installed: with a list of files and the note “Changes take effect after a server restart”.

8. Click Restart and confirm. Plugins are only loaded when the server starts.

Plugin sources#

The checksum confirms that the file arrived on the server exactly as the author published it. Upload plugins that are only on SpigotMC or the author's website by hand, see Manual installation.

Other labels in the results:

• External only – the author hosts the file elsewhere (often paid plugins). It can't be installed automatically; download it from the author's page and upload it by hand.
• Not tested on … – the author doesn't list support for your Minecraft version for that release. It may work, but there's no guarantee.
• Stable, Beta, Alpha – the release channel. On a server with players, install stable versions.

Manual installation#

Upload by hand for plugins that aren't in the catalog, such as paid plugins.

1. Download the plugin to your computer from the author's official page or from a catalog (Modrinth, Hangar, SpigotMC). The file must have the .jar extension. If you downloaded a .zip, unpack it on your computer and look for the .jar inside.
2. In the customer area, go to the Files tab and open the plugins folder.
3. Click Upload and choose the .jar file. You can also drag it into the list with your mouse. A single file can be at most 100 MB.
4. Restart the server in the Console tab with the Restart button.

The plugin has to sit directly in the plugins folder. The server doesn't read subfolders. In the Plugins tab, a plugin uploaded by hand shows up with the Uploaded manually label. The customer area doesn't track the version or updates of such a plugin.

Verification#

1. After the restart, watch the console. A plugin that loaded successfully reports itself with a line like this:

   [12:00:08 INFO]: [LuckPerms] Enabling LuckPerms v<VERSION>

   Instead of <VERSION> you'll see the plugin's version number.

2. Type plugins in the console. It lists the plugins. In the game you'll see colors: plugins that are running in green, plugins that failed to enable in red.

3. The version <PLUGIN_NAME> command shows details about a specific plugin, for example version LuckPerms.

Configuring a plugin (config.yml)#

Most plugins create a plugins/<PLUGIN_NAME> folder with a config.yml file in it on first start. For example, LuckPerms keeps its settings in plugins/LuckPerms/config.yml.

1. In the Console tab, stop the server with the Stop button. Some plugins rewrite their file when shutting down and your changes would be lost.
2. In the Files tab, open plugins/<PLUGIN_NAME>/config.yml and click Edit.
3. Change the values and save (Ctrl+S).
4. Start the server.

.yml files use the YAML format. It's picky about small details:

# A line starting with a hash is a comment; the server ignores it.
nastaveni:
  zprava: "&aWelcome to the server!"
  max-domovu: 3
  zapnuto: true
  zakazane-svety:
    - world_nether
    - world_the_end

• Indent with spaces only, never tabs. A tab causes a loading error. Indentation decides what belongs under what (zprava belongs under nastaveni).
• Always put a space after the colon: max-domovu: 3, not max-domovu:3.
• Put text with special characters in quotes. Especially text that starts with & or contains : or #.
• A list is a series of lines starting with a hyphen and a space, indented under the key.
• true and false mean on and off.

Updating plugins#

1. In the Plugins tab, stay on the Installed sub-tab.
2. Click Check for updates. You'll see either “Everything is up to date.” or “Updates available:” with a count.
3. On the plugin, click Update to …, check the dialog and confirm with Update.
4. Restart the server.

Before updating, read the changelog on the project page (the Project page link). Major versions (for example from 2.x to 3.x) can change the configuration. Before a bigger update, make a backup, see Game server backups. To update a plugin you uploaded by hand, delete the old .jar and upload the new one. Two files of the same plugin in one folder cause an error.

Disabling and removing a plugin#

• Disable – the plugin won't load on the next start, but it stays on disk along with its settings. The file is renamed to <file>.jar.disabled. The Enable button brings it back.
• Remove – deletes the plugin file from the plugins folder. The plugin's settings and data in the plugins/<PLUGIN_NAME> folder stay, so the plugin finds them again if you reinstall it.

Changes take effect after a server restart.

Security#

• Only download plugins from catalogs (Modrinth, Hangar, SpigotMC) or from the author's official page.
• Never install “cracked” or “leaked” paid plugins. They're often modified so an attacker can take control of your server or get operator rights.
• Don't install plugins nobody has updated in years. They often don't work with new versions and have known bugs.
• Don't install plugins that do the same thing side by side (for example two permission plugins).

You'll find proven plugin tips in the article Recommended plugins.

Troubleshooting#

Look for plugin errors in the console while the server starts. The full log is in the logs/latest.log file (the Files tab).

Could not load 'plugins/….jar' in folder 'plugins' and UnknownDependencyException#

[00:00:00] [Server thread/WARN] Could not load 'plugins/MyAwesomePlugin-1.0.0.jar' in folder 'plugins'
[00:00:00] [Server thread/WARN] org.bukkit.plugin.UnknownDependencyException: Unknown/missing dependency plugins: [Vault]. Please download and install these plugins to run 'MyAwesomePlugin'.

The plugin is missing another plugin it depends on. Its name is in the square brackets (here Vault). Install it and restart the server.

Invalid plugin.yml#

The file isn't a Paper plugin. Most often it's a mod for Fabric or Forge, or an incomplete download. Download the right file again.

Ambiguous plugin name#

The plugins folder has two versions of the same plugin. Delete the older file.

UnsupportedClassVersionError … class file version 69.0#

The plugin needs a newer Java than the server runs on. The class version number maps to Java: 65 = Java 21, 69 = Java 25. The plugin is most likely made for a newer Minecraft version. Download the plugin version for your Minecraft version, or update the server, see Changing the version and software.

Error occurred while enabling … (Is it up to date?)#

The plugin loaded but crashed while being enabled. Below this line is the error output. The most common causes are an unsupported Minecraft version, a missing dependency or an error in its configuration. Check the plugin version and go through its config.yml.

The plugin reports an error in config.yml#

The console shows a YAML error with a line number, often InvalidConfigurationException, mapping values are not allowed here or a mention of a tab. Open the file and check that line: a tab instead of spaces, a missing space after a colon, or text with special characters that isn't in quotes.

The server won't start after installing a plugin and you don't know which one it is#

Disable plugins in batches. In the Plugins tab, disable half of them, restart, and depending on the result continue with the half that has the problem. You can also disable a plugin by hand by renaming its file, for example to Plugin.jar.disabled.

“A software change or modpack install is running on this server”#

Wait until the change in the Software tab finishes. Then you'll be able to edit plugins.

If you can't fix the error, send us the logs/latest.log file, see how to contact support.

Further reading#

• Paper: adding plugins (opens in a new window)
• Paper: basic troubleshooting (opens in a new window)
• Hangar (opens in a new window)
• Modrinth: plugins (opens in a new window)