How to Configure a Paper Server

1. Take stock of the files Paper creates

On first start Paper writes its configuration and the server properties into the server root. The three that matter for tuning are config/paper-global.yml, config/paper-world-defaults.yml and spigot.yml; server.properties holds the vanilla settings Paper also honours.

Every one of these files is regenerated on start with comments. Paper copies existing values back in, so your edits survive restarts; keys it does not recognise are reset to defaults. That means a typo in a key name does nothing visible, which is the first thing to check when a setting "does not work".

server.properties          vanilla settings
config/
  paper-global.yml         server-wide Paper behaviour
  paper-world-defaults.yml defaults for every world
spigot.yml                inherited Spigot settings
world/                     the world itself

2. Edit paper-global.yml for server-wide behaviour

paper-global.yml is the file to change when the problem is not about the world: packet limits, the watcher for file changes, commands sent over chat, how the console handles colour, and the item-obfuscation settings that stop clients reading each other's item data.

Change it, then run /paper reload rather than a full restart. The config is small enough to read end to end in ten minutes, which is a better use of an evening than copying values from a list.

_version: 31
watchers:
  enable-x25519-server-list-encryption: true
packet-limiter:
  kick-message: Connection throttled! Please wait before reconnecting.
commands:
  console-audit-opened: true

/paper reload

3. Edit paper-world-defaults.yml for gameplay and loading

This is the file most administrators mean when they say "Paper settings". It owns entity behaviour and spawn limits, chunk loading and saving, entity collisions, hoppers, command blocks, anti-Xray, scoreboards and the per-world gameplay options such as mob griefing.

Everything in this file is a default that individual worlds can override, which is the next step. Change the default once here rather than in every world folder.

entity:
  spawning:
    spawn-limits:
      monsters: 70
      animals: 10
      water-animals: 5
      ambient: 15
    per-player-mob-spawns: true
  despawn-ranges:
    softer:
      monsters:
        horizontal: 40
        vertical: 15
chunks:
  auto-save-interval: default
  min-chunk-unload-count: 50
hopper:
  hopper-transfer: 8
  cooldown-when-full: true
collisions:
  max-entity-collisions: 8
  only-players-collide: false

4. Override single worlds where you need different behaviour

Paper resolves each setting by looking in the world's own file first and falling back to the defaults file. A world's file is world/dimensions/<namespace>/<key>/paper-world.yml, and it is nearly empty on purpose: only the settings you add are overridden, everything else is inherited.

So a creative arena world can have its own spawn limits and its own mob griefing without touching the survival overworld. Add only the keys you want, keeping the same nesting and the _version line the file already has.

_version: 31
entity:
  spawning:
    spawn-limits:
      monsters: 5

5. Know the vanilla and Spigot settings you will still meet

Some behaviour people expect to find in Paper lives in the files Paper inherited. server.properties still owns view distance, simulation distance, the whitelist, the world name and the port, and it needs a restart to take effect. spigot.yml owns a handful of settings Paper keeps for compatibility, such as entity activation range and the animal and monster activation ranges.

Leave spigot.yml alone unless you know a specific key you want: its defaults are what Paper was tuned against, and changing activation ranges is one of the easiest ways to make a server slower.

view-distance=6
simulation-distance=6
white-list=false
level-name=world

Good to know

• Configuration files are rewritten with comments on every start. Never keep your own notes inside them; keep a copy elsewhere and diff it against the regenerated file when you are unsure what you changed.
• Change one file per restart and note what you touched. Paper logs configuration reloads, so the log tells you when a file was read.
• The Paper settings guide covers the specific values worth setting on a small server and what each one trades away.
• The knowledge base entry on Paper explains which project each config file came from, which matters when a key looks like it should be somewhere else.

Common questions

Sources

Official documentation this guide was checked against.

• PaperMC docs: configuration files and per-world configuration
• PaperMC docs: world configuration defaults
• Minecraft Wiki: server.properties