plugin.yml explained

plugin.yml is the small text file that introduces your plugin to Paper: its name, its version, where its main class is, and what it needs. On this page you will learn every field, which ones are required, how YAML works, and how to read the errors Paper prints when the file is wrong.

What plugin.yml is for

A plugin jar is just a zip file full of compiled classes. When the server starts, Paper opens every jar in the plugins folder and looks for one file at the top level: plugin.yml. That file is your plugin's ID card. Without it, Paper does not even know the jar is a plugin.

From plugin.yml, Paper learns:

• what the plugin is called and which version it is,
• which class to create as the main class (the one that extends JavaPlugin, see the plugin lifecycle),
• which Minecraft version it was written for,
• which other plugins it needs, and which permissions it uses.

Paper reads all of this before it runs any of your Java code. That is why a mistake in plugin.yml stops your plugin from loading at all, no matter how good your code is.

In your project, the file lives in src/main/resources. When you build, Gradle copies everything in that folder into the jar, so plugin.yml ends up at the top of the jar where Paper looks for it:

The smallest plugin.yml that works

Four fields are required. Here is a complete, working plugin.yml with nothing else in it:

11name: HelloYaml22version: '1.0.0'33main: com.example.pluginymlminimal.HelloYamlPlugin44api-version: '26.3'

And the main class it points to:

11package com.example.pluginymlminimal;2 3import org.bukkit.plugin.java.JavaPlugin;4 25public final class HelloYamlPlugin extends JavaPlugin {6 7    @Override8    public void onEnable() {9        getLogger().info("Paper found me through plugin.yml.");10    }11}

The four required fields in detail

name may only contain letters, digits, underscores, periods and dashes. Avoid spaces: they are turned into underscores or refused, depending on the loader. Paper also refuses the names Bukkit, Minecraft and Mojang. Choose a name once and keep it: renaming later moves the data folder and breaks every plugin that depends on yours.

version can be any text, but most developers use three numbers: '1.4.2'. Releasing and sharing your plugin explains what each number means.

main is the most common reason a new plugin does not load. If you rename the package or the class in IntelliJ, you must change this line too, because IntelliJ does not always update it for you.

api-version tells Paper which version of the API you wrote against. If it is newer than the server (say '26.4' on a 26.3 server), Paper refuses to load the plugin, because it cannot promise that your code will work. If it is missing completely, Paper treats your plugin as a very old plugin from before Minecraft 1.13, prints a warning, and turns on a slow compatibility mode. So always include it.

YAML in five minutes

plugin.yml is written in YAML, a format for writing data that people can read. You will use the same format for config.yml in Configuration files, so it pays to learn the rules once.

Keys and values

Each line is a key, a colon, a space, and a value. The space after the colon is required.

1name: ServerInfo2website: https://example.com/serverinfo

Nesting with indentation

A key can hold more keys inside it instead of a value. You show that by indenting the inner keys. This is how permissions are written:

1permissions:2  serverinfo.news:3    description: See the server news when joining.4    default: true

Read it like folders: permissions contains serverinfo.news, which contains description and default. The rules:

• Use spaces, never tabs. A single tab character makes the whole file invalid. IntelliJ inserts spaces when you press Tab in a YAML file, but text copied from websites sometimes contains real tabs.
• Be consistent. Two spaces per level is the usual choice. Keys at the same level must start in exactly the same column.

Lists

Some fields hold a list of values. YAML has two ways to write a list, and both mean the same thing:

1authors: [Jace, Alex]

1authors:2  - Jace3  - Alex

A list with one item is still a list: depend: [Vault]. Writing depend: Vault without the brackets is a classic mistake, and Paper refuses it.

Why the quotes around versions?

YAML guesses the type of every value. true becomes true/false, 42 becomes a number, and anything else becomes text. That guessing causes a nasty surprise with versions:

1version: 1.10

YAML reads 1.10 as the decimal number one point one, and Paper shows your plugin as version 1.1. The same thing would happen to an api-version like 26.10. Quotes tell YAML "this is text, do not guess", so '1.10' stays exactly 1.10. Quote every version, every time, and the problem can never happen.

A bigger plugin.yml

Most real plugins use a few more fields. This example belongs to a small plugin called ServerInfo, which greets players with server news and shows staff some extra details:

1name: ServerInfo2version: '1.2.0'3main: com.example.pluginymlfull.ServerInfoPlugin4api-version: '26.3'15description: Greets players with server news and shows staff extra details.26authors: [Jace, Alex]37contributors: [Steve]48website: https://example.com/serverinfo59prefix: Info610load: POSTWORLD711softdepend: [LuckPerms]812permissions:13  serverinfo.news:14    description: See the server news when joining.915    default: true16  serverinfo.details:17    description: See plugin details when joining.1018    default: op19  serverinfo.admin:20    description: Everything ServerInfo offers.21    default: op1122    children:23      serverinfo.news: true24      serverinfo.details: true

The code can read every one of these values back through getPluginMeta(), so you never have to repeat them in Java:

1package com.example.pluginymlfull;2 3import io.papermc.paper.plugin.configuration.PluginMeta;4import org.bukkit.plugin.java.JavaPlugin;5 6public final class ServerInfoPlugin extends JavaPlugin {7 8    @Override9    public void onEnable() {110        PluginMeta meta = getPluginMeta();211        getLogger().info(meta.getName() + " " + meta.getVersion() + " by " + String.join(", ", meta.getAuthors()));312        getLogger().info("Website: " + meta.getWebsite());413        getLogger().info("Load order: " + meta.getLoadOrder());14 515        boolean luckPermsFound = getServer().getPluginManager().isPluginEnabled("LuckPerms");16        if (luckPermsFound) {17            getLogger().info("LuckPerms is installed, so ranks can get the serverinfo permissions.");18        } else {19            getLogger().info("LuckPerms is not installed. That is fine, it is only a soft dependency.");20        }21 622        getServer().getPluginManager().registerEvents(new NewsListener(meta), this);23    }24}

[14:02:07 INFO]: [Info] Enabling ServerInfo v1.2.0[14:02:07 INFO]: [Info] ServerInfo 1.2.0 by Jace, Alex[14:02:07 INFO]: [Info] Website: https://example.com/serverinfo[14:02:07 INFO]: [Info] Load order: POSTWORLD[14:02:07 INFO]: [Info] LuckPerms is not installed. That is fine, it is only a soft dependency.

The listener uses the two permissions from plugin.yml:

18@EventHandler19public void onJoin(PlayerJoinEvent event) {20    Player player = event.getPlayer();121    if (player.hasPermission("serverinfo.news")) {22        player.sendRichMessage("<gold>News:</gold> <gray>The new spawn opens this weekend!");23    }224    if (player.hasPermission("serverinfo.details")) {25        player.sendRichMessage("<dark_gray>Running <name> <version>",26            Placeholder.unparsed("name", meta.getName()),27            Placeholder.unparsed("version", meta.getVersion()));28    }29}

An operator who joins sees both lines; everyone else sees only the news:

Every field at a glance

You do not need to type any of this from memory. The plugin.yml Builder asks you a few questions and writes a valid file for you.

load: STARTUP

Almost every plugin should leave load out. STARTUP is for the rare plugin that must run before the worlds exist, such as a custom world generator that the server needs while it creates the worlds. A STARTUP plugin cannot use any world in onEnable, because there are none yet.

depend, softdepend and loadbefore

These three fields control the order in which plugins are enabled. Use them when your plugin talks to another plugin:

1depend: [Vault]2softdepend: [LuckPerms, PlaceholderAPI]3loadbefore: [Essentials]

• depend: "I cannot work without these." If Vault is missing, Paper does not load your plugin and prints Unknown/missing dependency plugins: [Vault]. Please download and install these plugins to run 'ServerInfo'.
• softdepend: "I use these if they are installed." Your plugin always loads, after them if they are there. Check with isPluginEnabled before using them.
• loadbefore: "Enable me before these." Rarely needed, for example when another plugin should see something yours sets up.

The names must match the other plugin's own name exactly, capital letters included. Working with other plugins shows how to actually use Vault, LuckPerms and PlaceholderAPI from your code.

libraries

1libraries:2  - org.apache.commons:commons-lang3:3.17.0

Each entry is a Java library written as group:name:version, the same way you would add it in Gradle. When the server starts, Paper downloads it from Maven Central and makes it available to your plugin, so you do not have to pack it into your jar. You still add it to build.gradle.kts as compileOnly so your code compiles. Gradle and Maven reference covers dependencies.

folia-supported

Folia is a version of Paper that runs different areas of the world on different threads. It only loads plugins that say folia-supported: true, because most plugins are not safe there. Paper itself ignores the line. Only add it once your plugin really follows Folia's rules.

permissions

Each permission can have a description, a default and children. The default decides who has the permission when no permissions plugin says otherwise:

Permissions explains nodes, children and permissions plugins in depth.

commands (the classic way)

Older tutorials declare every command in plugin.yml:

1commands:2  spawnzombie:3    description: Spawns a zombie next to you.4    usage: /spawnzombie [amount]5    aliases: [sz]6    permission: myplugin.spawnzombie

This still works for plugin.yml plugins, together with getCommand("spawnzombie").setExecutor(...) in your code. New code should register commands in Java instead, which needs nothing in plugin.yml: see Commands, part 1. Commands, part 3 teaches the classic style so you can read older code.

When plugin.yml is wrong

Paper reads plugin.yml before it runs your code, so a mistake here means your plugin never starts. You will not see "Enabling YourPlugin" in the console, and /plugins does not list it at all. Instead there is an ERROR near the top of the console log, before the worlds load. Scroll up, or open logs/latest.log, and look for these lines. Each one names the problem clearly once you know what to look for:

Here is the main class error as it really looks, shortened to the important lines. The Caused by line underneath repeats the class name Java tried to find:

org.bukkit.plugin.InvalidPluginException: Cannot find main class `com.example.shopsigns.ShopSignsPlugin'	at org.bukkit.plugin.java.PluginClassLoader.<init>(PluginClassLoader.java:84) ~[paper-api-26.3.build.142-beta.jar:?]	...Caused by: java.lang.ClassNotFoundException: com.example.shopsigns.ShopSignsPlugin

If you are not sure what an error means, paste it into the Error Doctor.

plugin.yml or paper-plugin.yml?

Paper understands a second, newer descriptor called paper-plugin.yml. You will see it in some projects, including the clean-slate-paper-plugin template. The two are not interchangeable: a plugin uses one or the other.

Start with plugin.yml. When you are ready for more, Paper plugins: paper-plugin.yml, bootstrapper and loader explains the newer format.

Mistakes to avoid

• Forgetting to update main after renaming a class or package.
• Tabs in the indentation, often from copied text.
• Unquoted versions: 1.10 becomes 1.1.
• A single value where a list belongs: depend: Vault instead of depend: [Vault].
• Putting plugin.yml in the wrong folder. It belongs in src/main/resources, not next to your Java files.
• Wrong capital letters in main, in dependency names, or in the keys themselves.

1name: Shop Signs!2version: 1.103main: com.example.shopsigns.ShopSignsPlugin4api-version: 26.35description: Lets players make simple shop signs.6softdepend: LuckPerms7permissions:8  shopsigns.create:9    description: Create shop signs.10   default: true

1name: ShopSigns12version: '1.10'23main: com.example.pluginymlexercise.ShopSignsPlugin4api-version: '26.3'5description: Lets players make simple shop signs.36softdepend: [LuckPerms]7permissions:8  shopsigns.create:9    description: Create shop signs.410    default: true

1shopsigns.admin:2  description: Everything ShopSigns offers.3  default: op4  children:5    shopsigns.create: true

Recap

• plugin.yml lives in src/main/resources and ends up at the top of your jar.
• Four fields are required: name, version, main and api-version ('26.3').
• main is the package plus the class name of your JavaPlugin class, exactly.
• YAML uses spaces for nesting (never tabs), two styles of lists, and quotes to stop type guessing.
• depend means required, softdepend means optional; both make Paper enable those plugins first.
• A broken plugin.yml stops the plugin before any code runs; the console error names the field.

Quick quiz

Next steps

• plugin.yml Builder: make a valid file from a form.
• Events and listeners: make your plugin react to the game.
• Permissions: everything about permission nodes.