paper-plugin.yml Format

Complete reference for the paper-plugin.yml configuration file

The paper-plugin.yml file is the plugin descriptor for Paper plugins. It must be located in your plugin’s src/main/resources directory and contains metadata about your plugin.

Paper supports both paper-plugin.yml (modern format) and plugin.yml (legacy Bukkit format). The paper-plugin.yml format is recommended for new plugins.

Required Fields

These fields must be present in every paper-plugin.yml file:

name

The unique identifier for your plugin. Used for dependency resolution and the data folder name.

name: MyPlugin

Constraints:

• Only alphanumeric characters, underscores, hyphens, and periods: [a-zA-Z0-9_\-\.]
• Must be unique across all loaded plugins

version

The version of your plugin. No specific format is enforced, but semantic versioning is recommended.

version: 1.0.0

main

The fully qualified class name of your main plugin class. Must extend org.bukkit.plugin.java.JavaPlugin.

main: com.example.myplugin.MyPlugin

Optional Fields

api-version

The Minecraft API version your plugin is built for (e.g., 1.21, 1.20). This helps maintain compatibility.

api-version: '1.21'

Always specify the api-version to ensure your plugin works correctly across different Paper versions.

description

A human-friendly description of what your plugin does.

description: A plugin that adds custom gameplay features

author / authors

The author(s) of the plugin. Use author for a single author or authors for multiple.

author: PlayerName

authors:
  - PlayerOne
  - PlayerTwo

contributors

People who contributed to the plugin but are not primary authors.

contributors:
  - ContributorOne
  - ContributorTwo

website

A website URL for the plugin or author.

website: https://example.com

prefix

Custom prefix for the plugin’s logger. By default, the plugin name is used.

prefix: MyCustomPrefix

Dependency Management

load

Specifies when the plugin should be loaded during server startup.

load: STARTUP

Valid values (from org.bukkit.plugin.PluginLoadOrder):

• STARTUP - Load during server startup (before worlds)
• POSTWORLD - Load after worlds are loaded (default)

dependencies

Plugins that must be loaded before this plugin. The server will fail to load your plugin if these are missing.

dependencies:
  server:
    - RequiredPlugin
    - AnotherRequiredPlugin

If any listed dependencies are not installed, your plugin will fail to load.

softdepends

Plugins that should load before this plugin if they’re present, but aren’t required.

softdepends:
  server:
    - OptionalPlugin

loadbefore

Plugins that should load after this plugin, without being dependencies.

loadbefore:
  server:
    - PluginToLoadAfter

provides

Other plugin names that this plugin provides/implements.

provides:
  server:
    - AlternativePluginName

Advanced Features

bootstrapper

A class implementing io.papermc.paper.plugin.bootstrap.PluginBootstrap for early initialization.

bootstrapper: com.example.myplugin.MyPluginBootstrap

The bootstrapper runs before the main plugin class and allows initialization before the server fully loads.

Bootstrappers are experimental. Only use API methods documented to work during bootstrap.

loader

A class implementing io.papermc.paper.plugin.loader.PluginLoader for configuring the plugin’s classpath.

loader: com.example.myplugin.MyPluginLoader

Useful for loading external libraries at runtime.

Permissions

defaultPerm

The default permission level for all permissions defined in this plugin.

defaultPerm: OP

Valid values (from org.bukkit.permissions.PermissionDefault):

• TRUE - Everyone has permission by default
• FALSE - No one has permission by default
• OP - Only operators have permission (default)
• NOT_OP - Only non-operators have permission

permissions

Define permissions for your plugin.

permissions:
  myplugin.use:
    description: Allows using the plugin
    default: true
  myplugin.admin:
    description: Administrative permissions
    default: op
    children:
      myplugin.use: true

Complete Example

Here’s a complete example from the Paper test plugin:

name: Paper-Test-Plugin
version: ${version}
main: io.papermc.testplugin.TestPlugin
description: Paper Test Plugin
author: PaperMC
api-version: ${apiversion}
load: STARTUP
bootstrapper: io.papermc.testplugin.TestPluginBootstrap
loader: io.papermc.testplugin.TestPluginLoader
defaultPerm: FALSE
permissions:
dependencies:

Migration from plugin.yml

If you’re migrating from the legacy plugin.yml format:

1. Rename plugin.yml to paper-plugin.yml
2. Update dependency format from flat lists to the new structured format:
   # Old format (plugin.yml)
   depend: [PluginA, PluginB]
   
   # New format (paper-plugin.yml)
   dependencies:
     server:
       - PluginA
       - PluginB
   
3. Commands are no longer supported in YAML - use the JavaPlugin.registerCommand() method instead

Paper plugins do not support YAML-based command declarations. You must register commands programmatically using JavaPlugin.registerCommand().