Installing Plugins

Plugins are the most powerful way to extend the functionality of Paper beyond the configuration files. Functionality added by plugins can range from making milk restore hunger or dead bushes grow, to adding entirely new game modes, items, or administrative tools.

Malicious Plugins

Ensure you fully trust the source of any plugin before installing it. Plugins are given full and unrestricted access to not only your server process but also the machine it runs on. Because of this, it is imperative that plugins only be installed from trusted sources. Be careful!

Finding plugins

Before installing a plugin, you’ll need to find what you want to install. The best places to find plugins are:

• Hangar (Paper’s official plugin repository)
• Modrinth
• SpigotMC / BukkitDev

Installing plugins

1. Download the desired plugin file. Ensure the file ends in .jar. (If distributed inside a .zip archive, extract it to find the .jar file).
2. In SquidServers, click Server Files for your server.
3. Open the plugins folder.
4. Drag and drop the .jar file into the plugins folder.
5. Restart your server.
6. Check your work: Run /plugins in-game or type plugins in the server console. Active plugins will be listed in green. If a plugin is listed in red or not listed at all, see Troubleshooting below.

Troubleshooting

Check your logs

The first step to troubleshooting plugin installation is to check your server log. Recent logs are stored in logs/latest.log.

Missing dependencies

If you see an error like:

[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'.

This means the plugin requires another plugin (a dependency) to function. Download and install the required dependency (e.g. Vault) into the plugins folder as well.

Invalid plugin.yml

If you see an error like:

[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.InvalidDescriptionException: Invalid plugin.yml

This indicates the file is not a valid Paper plugin. Common causes:

1. You downloaded a Forge or Fabric mod instead of a Paper plugin.
2. The download was incomplete or corrupted. Try re-downloading the file.

Duplicate plugin names

If you see an error like:

[00:00:00] [Server thread/WARN] Ambiguous plugin name `Essentials' for files `plugins/EssentialsX-2.19.4.jar' and `plugins/Essentialsx-2.20.0-dev.jar' in `plugins'

You have two versions of the same plugin installed. Delete the older .jar file from the plugins folder and restart your server.

If nothing is logged

If nothing is logged, the server did not attempt to load the plugin. Ensure:

1. The .jar file is placed directly in the root of the plugins folder (not in a subfolder).
2. The file extension is .jar.

If both conditions are met and the plugin still does not load, reach out for support on our Discord.

-# Based on Adding Plugins by papermc.io wiki, credit to PaperMC contributors.