Optimize Paper for Performance: Safe Config Settings

Tune Paper for better TPS without breaking farms: which settings in the Paper, Spigot and Bukkit config files to change, and which to leave alone.

5 min read · Updated Sep 23, 2026 · By GuavaHost Team

Paper already runs Minecraft far more efficiently than vanilla, but a handful of settings in its config files can buy you noticeably better TPS on a busy server. This guide covers which files hold those settings on your version, the changes that are safe for almost everyone, the ones that trade vanilla behaviour for speed, and the ones to leave alone.

One rule before you touch anything: measure first. Run spark, change a few settings, then measure again. Find what's causing lag with spark shows how. If one plugin or farm is eating half your tick, no config tweak will fix that.

Which files, and where

The file layout depends on your Minecraft version:

Paper 1.19 split the old paper.yml into the two files in the config folder. If you run an older version, the same ideas apply, but the setting names and positions in paper.yml differ. Each world can also have its own paper-world.yml that overrides the defaults for that world only; you rarely need it.

Purpur uses all of these files too, plus its own purpur.yml.

How to edit safely

1. Take a backup on the Backups tab.
2. Stop the server.
3. Open the file on the Files tab. Find the existing setting and change its value. Do not paste in a second copy of a section, because YAML (the format these files use) does not allow the same key twice.
4. Keep the indentation exactly as it was, using spaces, never tabs.
5. Press Save Content and start the server. Watch the Console for errors about the file.

Restart rather than using reload; config changes are only read reliably at startup.

Start with server.properties

The two biggest levers are not in Paper's files at all: view-distance and simulation-distance in server.properties. Lowering simulation distance is usually the single biggest win available. See View distance vs simulation distance for values.

In spigot.yml, leave view-distance and simulation-distance under world-settings set to default, so server.properties stays the one place that controls them.

Pre-generating your world removes the other big source of lag, generating terrain while players explore. See Set the world spawn, world border and pre-generate chunks.

Safe wins in paper-world-defaults.yml

These are safe for almost every server. Paths are shown with dots, so chunks.prevent-moving-into-unloaded-chunks means the prevent-moving-into-unloaded-chunks line inside the chunks: section.

For entity-per-chunk-save-limit, change the existing -1 values for the projectile-type entries, for example 16 for arrow and experience_orb, and 8 for snowball and ender_pearl. Anything above the limit is simply not saved when the chunk unloads.

When you are done, that part of the file looks something like this:

chunks:
  entity-per-chunk-save-limit:
    arrow: 16
    experience_orb: 16
    snowball: 8
  prevent-moving-into-unloaded-chunks: true

Trade-offs: faster, but less vanilla

These help on busy servers, but each changes gameplay a little. Change them one at a time and tell your players.

In spigot.yml, under world-settings: default:

• entity-activation-range: entities further from players than these ranges tick less often. Lowering them, for example animals: 16, monsters: 24 and misc: 8, saves a lot of work, but farms that rely on mobs acting far from any player slow down.
• mob-spawn-range: keep it no higher than your simulation-distance, so mobs are not spawned in chunks that are not being ticked.
• nerf-spawner-mobs: true: mobs from spawners get no AI. A big saving on spawner farms, but those mobs stand still, so check your farm design still works.
• merge-radius: a modest increase, such as item: 3.5 and exp: 4.0, means fewer dropped-item entities. Push it too far and items start merging through walls.

In bukkit.yml

• spawn-limits: caps on mobs. The default monsters: 70 can drop to around 50 on a busy server. With Paper's per-player mob spawning, which is on by default, these caps apply per player.
• ticks-per.monster-spawns: how often the game tries to spawn monsters. The default is 1, every tick; 5 to 10 cuts the cost with little visible difference.

In paper-world-defaults.yml

• collisions.max-entity-collisions: the default 8 can drop to 2. Crowded mobs push each other less, which can matter for some farms.

Leave these alone (unless you know what breaks)

• hopper.disable-move-event: turning it on stops protection plugins seeing hoppers move items, which can let players steal from claimed chests.
• ticks-per.hopper-transfer and hopper-check in spigot.yml: changing them breaks hopper clocks and item sorters.
• misc.redstone-implementation: the alternative engines are faster but change redstone timing, so big contraptions can behave differently.
• entities.armor-stands.tick: turning it off stops armor stands reacting to gravity and pistons.
• tick-inactive-villagers in spigot.yml: turning it off can stall iron farms and trade restocking.
• unsupported-settings in paper-global.yml: these re-enable exploits and duplication glitches Paper fixes on purpose.
• Thread counts under chunk-system in paper-global.yml: the default -1 sizes them automatically.
• Watchdog and timeout settings: raising them hides freezes instead of fixing them. See Minecraft server crashing?.

paper-global.yml in general is best left at its defaults. Almost all of the useful tuning is per world.

Measure again

After restarting, check tps and mspt in the Console (see Reading TPS and MSPT), and run another spark profile under similar load. If nothing moved, put the setting back and look elsewhere. If you have tuned everything and your server is still short on headroom, How much RAM does my Minecraft server need? covers when more resources are the honest answer.

Still stuck? Jump into our Discord at discord.gg/GuavaHost and the team will help you out.

• paper
• optimization
• performance
• tps
• spigot.yml
• bukkit.yml
• paper-world-defaults
• purpur

Host a Minecraft Java server From $3.99/mo, with instant setup and DDoS protection.

Still need help? Our team is online 24/7 to answer questions.

Contact support