Voxen logoVOXEN

// voxen field notes

plugin.yml Explained: Every Field With a Working Example (2026)

· updated · 8 min read · [ EXPLAINER ] · by Matteo Orazietti

Every Minecraft plugin .jar contains a plugin.yml file at its root. Before the server loads a single class from your plugin, it reads this file to learn the plugin's name, the main class to start, the Minecraft version it targets, which other plugins it needs, and which commands and permissions it adds. Get a field wrong and the plugin either fails to load or behaves as if it isn't there.

Where the file lives

In a Maven or Gradle project the file goes in src/main/resources/plugin.yml. The build copies everything in that folder to the root of the .jar, which is where the server looks. A file placed insrc/main/java is ignored.

A complete example

terminal — plugin.yml
name: HelloPlugin
version: 1.0.0
main: com.example.hello.HelloPlugin
api-version: '1.21'
description: Greets players and adds a /hello command.
authors: [YourName]
website: https://example.com
depend: [Vault]
softdepend: [PlaceholderAPI]
load: POSTWORLD
commands:
  hello:
    description: Says hello to the player
    usage: /hello
    aliases: [hi]
    permission: helloplugin.use
permissions:
  helloplugin.use:
    description: Allows using /hello
    default: true

Every field, explained

FieldRequiredWhat it does
nameYesThe plugin name shown in /plugins and in the console. It also prefixes commands, as in /helloplugin:hello.
versionYesYour plugin version, shown in /plugins. Quote it if it is a plain number.
mainYesFully qualified name of the class that extends JavaPlugin. Package, class name and capitalization must match the code exactly.
api-versionStrongly recommendedThe Minecraft version the plugin targets, for example '1.21' or '26.1'. Quote it. Without it the server treats the plugin as legacy and prints warnings.
authors or authorNoCredits. Both spellings are accepted.
descriptionNoFree text describing the plugin.
websiteNoProject URL.
dependNoPlugins that must be installed. Without them this plugin will not enable.
softdependNoPlugins used if they are present. It only affects load order.
loadNoSTARTUP loads the plugin before worlds are created, POSTWORLD (the default) loads it after.
commandsNoDeclares commands with description, usage, aliases and permission. The command also needs a handler in code.
permissionsNoDeclares permission nodes and their default: true, false, op or not op.
Quote the api-version. YAML reads an unquoted 1.20 as the number 1.2, so the server no longer sees the version you wrote. Write '1.20' instead.

Since 1.20.5 the api-version can name an exact release such as '1.21.4'. On 26.x write at least major.minor, such as '26.1': a bare '26' failed to load in a reported case, and '26.1' fixed it. The server refuses any plugin whose api-version is newer than the server itself, so a plugin declaring '26.2' will not load on a 26.1 server, and the console reports Unsupported API version.

Commands and permissions

Commands declared in plugin.yml show up in the server's command list and get a permission check before they run. The entry itself does not do anything: the command's name must also be handled in your code, for example in onCommand. If it isn't, the command is accepted but nothing happens.

Permissions work the same way. Declaring helloplugin.use with default: true lets everyone run the command. Set it to op to restrict it to operators, or to false to deny it unless a permissions plugin such as LuckPerms grants it.

Why a plugin won't load

  • Tabs or broken indentation. YAML uses spaces only. A tab produces an "Invalid plugin.yml" error and the plugin is skipped.
  • Wrong main class. If the package, class name or capitalization in main doesn't match the code, the server can't find the class and the plugin fails to enable.
  • File in the wrong place. A plugin.yml that isn't at the root of the .jar is invisible to the server. Open the .jar with any archive tool to check.
  • Missing dependency. A plugin listed under depend that isn't installed keeps this plugin disabled. Install the dependency or move it to softdepend if the plugin can run without it.
  • Unquoted api-version. The server may report an unsupported version even though you wrote the right one. Quote it.

Check it after the change

Restart the server and run /plugins. Green means it enabled. If the plugin is red or missing, the console explains why, starting from the first error line. The installation guide covers the rest of that check, and How to Fix Minecraft Plugin Errors covers the most common failures.

To see the whole file in context, build a small plugin with the first plugin tutorial, where plugin.yml is created step by step next to the Java code.