|
| 1 | +--- |
| 2 | +toc_max_heading_level: 4 |
| 3 | +slug: /adding-plugins |
| 4 | +description: Plugins are the most powerful way to extend the functionality of Paper beyond the configuration files. |
| 5 | +--- |
| 6 | + |
| 7 | +# Adding Plugins |
| 8 | + |
| 9 | +Plugins are the most powerful way to extend the functionality of Paper beyond the configuration |
| 10 | +files. Functionality added by plugins can range from making milk restore hunger or dead bushes grow, |
| 11 | +to adding entirely new and original game modes or items. |
| 12 | + |
| 13 | +:::danger[Malicious Plugins] |
| 14 | + |
| 15 | +Ensure you fully trust the source of any plugin before installing it. Plugins are given **full and |
| 16 | +unrestricted** access to not only your server but also the machine that it runs on. Because of this, |
| 17 | +it is imperative that plugins only be installed from trusted sources. Be careful! |
| 18 | + |
| 19 | +::: |
| 20 | + |
| 21 | +## Finding plugins |
| 22 | + |
| 23 | +Before installing a plugin, you'll need to find what you want to install. The best place to find plugins is [Hangar](https://hangar.papermc.io), Paper's plugin repository, but you can also find many plugins |
| 24 | +on [SpigotMC](https://www.spigotmc.org/resources/), |
| 25 | +[BukkitDev](https://dev.bukkit.org/bukkit-plugins), or the |
| 26 | +[PaperMC Forums](https://forums.papermc.io/forums/paper-plugin-releases/), while other plugins may |
| 27 | +release on [GitHub](https://github.com). One of the best ways to find plugins isn't to browse any of |
| 28 | +these sites directly but to search for plugins using a search engine. Searching for the function you |
| 29 | +desire followed by `Minecraft plugin` will often yield good results. |
| 30 | + |
| 31 | +:::tip[Spigot and Bukkit Plugins] |
| 32 | + |
| 33 | +Paper is compatible with both Spigot and Bukkit plugins. It's okay if a plugin does not explicitly |
| 34 | +mention Paper compatibility. It'll still work. |
| 35 | + |
| 36 | +::: |
| 37 | + |
| 38 | +## Installing plugins |
| 39 | + |
| 40 | +1. Once you've found the plugin you'd like to install, download it. Ensure the file you have |
| 41 | + downloaded ends in `.jar`. Some plugins also distribute as `.zip` files, in which case you will |
| 42 | + need to extract the file and locate the `.jar` for your platform, often labelled `bukkit` or |
| 43 | + `paper`. |
| 44 | +2. Once you have the plugin downloaded locally, locate the `plugins` folder from the root directory |
| 45 | + of your Paper server. |
| 46 | +3. Drag and drop the plugin file (`.jar`) into the `plugins` folder. If you are using a shared |
| 47 | + hosting service, you may need to use their web panel or SFTP to upload the plugin; however, the |
| 48 | + procedure will be the same. |
| 49 | +4. Restart your server. The plugin should load. |
| 50 | +5. Check your work. Once the server has finished loading, run the `/plugins` command in-game or type |
| 51 | + `plugins` into the console. You should see your freshly installed plugin listed in green. If it |
| 52 | + is not listed or is colored red, continue to [troubleshooting](#troubleshooting). A plugin listed |
| 53 | + in red means that it is not currently enabled. For a freshly installed plugin, this often means |
| 54 | + that the plugin failed to load. |
| 55 | + |
| 56 | +## Troubleshooting |
| 57 | + |
| 58 | +### Check your logs |
| 59 | + |
| 60 | +The first step to troubleshooting installing plugins is to check the log of your server. Your |
| 61 | +server's most recent logs will be stored to the `logs/latest.log` file. You may need to scroll near |
| 62 | +the beginning of this file to see when plugins were loaded. |
| 63 | + |
| 64 | +#### Missing dependencies |
| 65 | + |
| 66 | +If you see something like this: |
| 67 | + |
| 68 | +```log |
| 69 | +[00:00:00] [Server thread/WARN] Could not load 'plugins/MyAwesomePlugin-1.0.0.jar' in folder 'plugins' |
| 70 | +[00:00:00] [Server thread/WARN] org.bukkit.plugin.UnknownDependencyException: Unknown/missing dependency plugins: [Vault]. Please download and install these plugins to run 'MyAwesomePlugin'. |
| 71 | +``` |
| 72 | + |
| 73 | +This means that the plugin you tried to install is missing a dependency. A dependency, in this case, |
| 74 | +is another plugin that you must install for the first to function. While you will get a big scary |
| 75 | +error, the important line to look at is: |
| 76 | + |
| 77 | +```log |
| 78 | +[00:00:00] [Server thread/WARN] Unknown/missing dependency plugins: [Vault]. Please download and install these plugins to run 'MyAwesomePlugin'. |
| 79 | +``` |
| 80 | + |
| 81 | +This is telling you that in order to load `MyAwesomePlugin`, you must first install `Vault`. |
| 82 | + |
| 83 | +#### Invalid `plugin.yml` |
| 84 | + |
| 85 | +If you see something closer to this: |
| 86 | + |
| 87 | +```log |
| 88 | +[00:00:00] [Server thread/WARN] Could not load 'plugins/MyAwesomePlugin-1.0.0.jar' in folder 'plugins' |
| 89 | +[00:00:00] [Server thread/WARN] org.bukkit.plugin.InvalidDescriptionException: Invalid plugin.yml |
| 90 | +``` |
| 91 | + |
| 92 | +This means that what you have downloaded isn't a valid Paper plugin. This is generally caused by one |
| 93 | +of the following: |
| 94 | + |
| 95 | +1. The plugin you downloaded isn't a plugin at all, but instead a mod for Forge, Fabric, or similar. |
| 96 | + These will not run on Paper. |
| 97 | +2. The plugin failed to download completely. Especially when using tools such as `curl` or `wget`, |
| 98 | + you can easily download error pages rather than the plugin you intended. This may also be caused |
| 99 | + by a network issue. Attempt to download the plugin again. If you are using FTP (not SFTP or a web |
| 100 | + panel) to upload your plugin to a shared hosting service, ensure your FTP client is in `binary` |
| 101 | + and not `ASCII` mode. Consult the documentation for your FTP client for details. |
| 102 | + |
| 103 | +#### Ambiguous plugin name |
| 104 | + |
| 105 | +If you see something like this: |
| 106 | + |
| 107 | +```log |
| 108 | +[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' |
| 109 | +``` |
| 110 | + |
| 111 | +This means you have two plugins with the same name, which is not supported. In this case, two |
| 112 | +versions of EssentialsX are installed. Both the release `2.19.4`, and a development build of |
| 113 | +`2.20.0`. Ensure you only have one version of each plugin installed at one time. Delete the older |
| 114 | +version of the duplicate plugin, and restart your server. |
| 115 | + |
| 116 | +To prevent accidentally installing two versions of one plugin while updating, you can use |
| 117 | +the `update` folder as described in the [Update Guide](/paper/updating#step-2-update-plugins). |
| 118 | + |
| 119 | +#### Something else |
| 120 | + |
| 121 | +If you see an error, but it isn't similar to one of the above, attempt to read it yourself. While |
| 122 | +the full error may be large and scary, you likely only have to read the first one or two lines to |
| 123 | +understand what is going on. If you're not sure, do not hesitate to reach out for support on our |
| 124 | +[Discord](https://discord.gg/papermc) in the `#paper-help` channel. |
| 125 | + |
| 126 | +### If nothing is logged |
| 127 | + |
| 128 | +If nothing is logged, your server is likely not attempting to load any plugins. The conditions |
| 129 | +needed for the server to load a plugin are as follows: |
| 130 | + |
| 131 | +1. The file is at the root of the `plugins` folder, relative to its working directory. This is |
| 132 | + usually the same folder as the server JAR file. **Subdirectories of the `plugins` folder will not |
| 133 | + be checked.** All plugins must be in the root folder. |
| 134 | +2. The file ends in `.jar`. If your plugin does not end in `.jar`, what you have downloaded may not |
| 135 | + be a plugin. Note that some plugins distribute multiple JARs as `.zip` files. If this is the |
| 136 | + case, you have to extract them before installing the plugin. |
| 137 | + |
| 138 | +If both of these are true, and you still see no logs, please reach out for support on our |
| 139 | +[Discord](https://discord.gg/papermc) server in the `#paper-help` channel. We will be happy to |
| 140 | +assist you. |
0 commit comments