How to configure Minecraft plugins (config.yml basics)

Most plugins store their settings in a config.yml file inside their own folder under plugins. Edit that file in the file manager, save it, then restart the server or use the plugin's own reload command.

Where plugin configs live#

After a plugin runs once, it creates a folder named after itself:

plugins/
  Essentials/
    config.yml
  LuckPerms/
    config.yml
  WorldGuard/
    config.yml
    worlds/

Some plugins split settings into several files, such as messages.yml or lang/en.yml. The plugin's documentation explains what each file does.

Editing a config#

1. Stop the server, or at least plan to restart it after editing.
2. Open the file in the file manager.
3. Change the values you need. Keep the existing structure and indentation.
4. Save the file.
5. Restart the server and check the console for errors from that plugin.

YAML rules that trip people up#

Plugin configs use YAML. It is sensitive to spacing:

• Use spaces, never tabs. A tab causes an error like found character '\t' that cannot start any token.
• Indentation shows nesting. Child keys must be indented more than their parent, and siblings must line up exactly.
• Put a space after the colon: enabled: true, not enabled:true.
• Quote text with special characters. Values that start with &, *, !, %, @ or contain : should be in quotes.
• Lists use a dash and a space.

A correct example:

settings:
  enabled: true
  max-homes: 3
  join-message: "&aWelcome to the server, %player%!"
  disabled-worlds:
    - world_nether
    - world_the_end

If a config has a syntax error, the plugin usually prints the line and column number. Some plugins then reset the file to defaults and rename yours, so fix errors before restarting again.

Reloading vs restarting#

There are three ways to apply changes, from safest to riskiest:

Paper even makes you type /reload confirm and warns you not to use it. Plugins were not designed to be unloaded and loaded again while the server runs, and many keep old data in memory or fail to re-register listeners. If you see odd behaviour after a /reload, restart the server fully.

Tips#

• Back up first. Download a copy of the config, or take a snapshot, before big changes.
• Do not delete keys you do not understand. A missing key may be filled with a default that differs from what you expect.
• Color codes. Many plugins use & codes such as &a (green) and &c (red). Newer plugins may use MiniMessage tags like <green> instead, inside the YAML string.
• Regenerate a broken config. Rename the file to config.yml.bak and restart. The plugin writes a fresh default you can compare against.

Related#

• How to install plugins on a Paper server
• Plugin not loading