Paper configuration explained: paper-global.yml & paper-world-defaults.yml

This article is a reference: it neutrally explains which configuration files Paper has and what each section does. For concrete recommendations ("what should I set?"), see the companion article Optimize your Paper server: improve TPS & fix lag.

The configuration files at a glance

Since Paper 1.19, the former single paper.yml has been split into several files in the config/ folder:

Who wins on conflicts?

Besides Paper's files there are other configs. For overlapping settings, this rough order applies – the later/more specific layer wins:

server.properties  →  bukkit.yml  →  spigot.yml  →  paper-world-defaults.yml  →  paper-world.yml
   (vanilla base)      (Bukkit)      (Spigot)        (Paper defaults)            (per world)

• server.properties = vanilla base values (e.g. view-distance, difficulty)
• spigot.yml = Spigot settings (e.g. entity-activation-range, merge-radius)
• Paper = the most fine-grained layer; paper-world.yml beats the defaults

Ground rules before any change

• Stop the server – don't edit config files while it's running
• YAML syntax: indent with spaces only, never tabs
• Make a backup of the config/ files and the world before changing anything
• After starting, check the log file for warnings

The inheritance principle (often done wrong)

Out of the box, Paper sets no per-world overrides – there are only the defaults at first. To configure a single world differently, create a paper-world.yml there and copy in only the value you want to change – not the whole file.

• Standard worlds: <worldfolder>/paper-world.yml
• Custom dimensions (data packs): world/dimensions/<namespace>/<key>/paper-world.yml

Example – enable lootables.auto-replenish for one world only:

# only in world_the_end/paper-world.yml
lootables:
  auto-replenish: true

Two-world example with different mob limits:

# world/paper-world.yml  (main world: fewer monsters)
entities:
  spawning:
    spawn-limits:
      monster: 50

# world_nether/paper-world.yml  (Nether: more monsters allowed)
entities:
  spawning:
    spawn-limits:
      monster: 100

Every value you don't override still comes from paper-world-defaults.yml.

paper-global.yml – the sections

Server-wide settings. This table neutrally describes what each section is responsible for:

Via unsupported-settings and the world settings you can also, among other things, disable the Nether and toggle certain vanilla bug fixes (e.g. MC-159283, MC-163962).

paper-world-defaults.yml – the sections

Default values for worlds (overridable per world via paper-world.yml):

Verifying & safeguarding changes

• Some values can be re-read with /paper reload – when in doubt, restart the server
• After starting, check the log file for YAML errors and warnings
• Always back up before config changes – a single indentation typo can stop a world from loading
• Full, version-current reference: docs.papermc.io – Global and World

Where to next

• Concrete recommendations & fixing lag: Optimize your Paper server: improve TPS & fix lag
• Getting started: Optimizing Minecraft server performance
• No server yet? How to create a Minecraft server

Frequently asked questions

Where do I find the Paper configuration files?

The server-wide files live in the config/ folder: paper-global.yml and paper-world-defaults.yml. Overrides for a single world go into a paper-world.yml inside that world's folder.

What is the difference between paper-global.yml and paper-world-defaults.yml?

paper-global.yml applies server-wide and covers things like the chunk system and networking, while paper-world-defaults.yml sets the default values for all worlds. World-specific settings such as mob limits belong in the defaults or the per-world file.

How do I change a setting for one world only?

Create a paper-world.yml in that world's folder and put only the value you want to differ into it. Everything else is still inherited from paper-world-defaults.yml – copying the whole file over is the most common mistake.

Which file wins when settings conflict?

The later, more specific layer wins: server.properties, then bukkit.yml, spigot.yml, paper-world-defaults.yml and finally paper-world.yml. A per-world file therefore overrides every other layer.

Am I allowed to change the _version field at the top of the file?

No — _version drives Paper's automatic migration of the configuration files and is managed exclusively by Paper itself. Changing it by hand can break the migration on updates.

Why are my YAML changes not applied?

Usually it is tabs instead of spaces in the indentation, an edit made while the server was running, or the wrong file (defaults instead of per-world). Stop the server, check the indentation, restart and watch the log for warnings.