PerformanceMinecraft

Tune Paper and Spigot configs to cut lag

Change the Paper, Spigot and Bukkit settings that affect performance, with each default and what you give up by changing it.

Updated 24 Oct 20264 min read

On this page

Before you change anything
Start with the distances
spigot.yml
config/paper-world-defaults.yml
bukkit.yml
Check the result

Paper ships with sensible defaults, and a handful of settings in its config files are worth changing when a busy server drops below 20 TPS. This guide covers the ones with a documented effect on performance, what each default is and what you trade away by changing it. Spigot is not a server type here, but Paper reads spigot.yml and bukkit.yml as well as its own files.

Checked against Paper 26.3 (build 211) and PaperMC's configuration reference, October 2026.

Before you change anything

Measure first. Run spark profiler start --timeout 120 in the Console while the lag is happening. Paper bundles spark, so there is nothing to install. Reduce lag with plugins shows how to read the report, and you can also watch the TPS reading in the left rail.
Create a backup in the Backups tab.
Open the files in the File Manager, edit one value at a time and restart the server from the Console afterwards. Edit bukkit.yml, spigot.yml and Paper config gives the file locations and the safe way to save.

Warning

Paper's own troubleshooting page says to revert values you copied from a pre-made optimisation guide if you see strange farm, redstone or spawning behaviour. Change a few settings, measure, and keep the ones that helped.

Start with the distances

The Config Editor has View distance (chunks) and Simulation distance (chunks), both 10 by default. The editor's own note calls view distance the biggest lever on RAM and CPU, and simulation distance the cheaper one to cut. You can also set view-distance and simulation-distance under world-settings.default in spigot.yml, where default means "use the value from server.properties".

spigot.yml

These sit under world-settings.default.

Key	Default	What it does
`entity-activation-range`	animals 32, monsters 32, raiders 64, misc 16, water 16, villagers 32, flying-monsters 32	Distance in blocks from a player within which entities tick normally. Beyond it they tick less often.
`entity-activation-range.tick-inactive-villagers`	`true`	Keeps ticking villagers outside their activation range.
`mob-spawn-range`	8	How many chunks from a player mobs can spawn.
`ticks-per.hopper-transfer`	8	Ticks between hopper item moves.
`max-tnt-per-tick`	100	TNT processed per tick.

Lowering entity-activation-range can save a lot, but Paper's reference warns that items in water streams may rubber-band when misc is low. Reduce entity lag on a Paper server covers the entity settings in more detail.

config/paper-world-defaults.yml

Key	Default	What it does
`environment.optimize-explosions`	`false`	Caches entity lookups during an explosion. Our installer sets it to `true` only when the file already exists, so check the value in your file.
`misc.update-pathfinding-on-block-update`	`true`	Setting it to `false` can improve performance significantly with almost no noticeable effect on gameplay.
`hopper.ignore-occluding-blocks`	`false`	Set to `true` and hoppers ignore containers inside occluding blocks, which improves performance for hoppers checking where to insert items.
`hopper.disable-move-event`	`false`	Dramatically improves hopper performance, but breaks protection plugins and others that depend on that event.
`chunks.max-auto-save-chunks-per-tick`	24	The most chunks an auto-save writes in a single tick.
`tick-rates.mob-spawner`	1	How often spawners tick. A value of `-1` disables every spawner.

When config/paper-world-defaults.yml already exists, our installer sets optimize-explosions to true on Paper, Purpur and Folia, so a reinstall resets that line. Do not raise tick-rates.container-update above 1. Paper warns that higher values can cause item desync and visual lag.

bukkit.yml

spawn-limits holds the global mob caps, such as monsters: 70, animals: 10 and water-animals: 5. ticks-per.autosave is 6000. Paper lets a world override the limits in entities.spawning.spawn-limits in the world config, where -1 means "use bukkit.yml".

Check the result

Restart, repeat the spark profile under the same load and compare the TPS card. If a change made no difference, put the old value back so you are not carrying settings that do nothing.

Tip

Paper deprecates /reload for removal, and /paper reload is unsupported and does not reload spigot.yml. Restart after every edit.

Was this guide helpful?

Still stuck?

Talk to a real person, we answer fast.

Open a ticket
Paste the exact error and name your server, so we can look at it from our side.
New ticket
Ask on Discord
Chat with the team and other server owners.
Join Discord
Browse the Help Centre
Versions, mods, plugins, backups and RAM sizing, all in plain English.
All guides