Paper Config Optimization to Reduce Lag

This guide shows you how to tune your Paper server’s configuration files to reduce lag, improve tick rates, and create a smoother multiplayer experience. You’ll learn which settings matter most, how to adjust them safely, and what to avoid. No prior server admin experience is needed, but you should have access to your server’s files and be comfortable editing text files.

What You’ll Need

Access to your Paper server’s root directory (where server.properties, paper-global.yml, and spigot.yml are located).
A text editor (Notepad++, VS Code, or even nano on Linux).
Basic understanding of YAML syntax (indentation matters!).
Ability to restart your server to apply changes.
Optional: a server benchmarking tool or plugin to measure TPS (ticks per second) before and after changes.

Step-by-Step

Back up your current configuration files. Copy paper-global.yml, paper-world-defaults.yml, spigot.yml, and bukkit.yml to a separate folder. This lets you revert if something breaks.
Update Paper to the latest stable version. Lag fixes and performance improvements are constantly added. Use the update script or download the new jar from the official Paper site and replace the old one.
Open paper-global.yml and locate the chunk-loading section. Set chunk-loading.threads to a value between 2 and 4 (default is usually 2). More threads can speed up chunk generation, but too many can cause CPU thrashing. For most servers, 3 is a good balance.
Adjust entity-activation-range in paper-world-defaults.yml. This controls how far away entities (mobs, items) are still active. Lower values reduce CPU load. A common optimization is:
```
entity-activation-range:
  animals: 16
  monsters: 24
  raiders: 48
  misc: 8
  tick-inactive-villagers: false
```
These values are safe for most survival servers. If you have a large spawn area, you might reduce them further.
Enable optimize-explosions in paper-world-defaults.yml. Set optimize-explosions: true. This reduces the physics calculations for explosions, which can cause lag during TNT cannon use or wither fights.
Reduce mob-spawner-tick-rate in paper-world-defaults.yml. Change it from the default (often 1) to something like 2 or 3. This makes spawners check for mobs less frequently, reducing lag from large mob farms.
Set max-auto-save-chunks-per-tick in paper-world-defaults.yml. The default is often 24. Lowering it to 10 spreads out the auto-save over more ticks, preventing the classic “save lag” spike every few minutes.
In spigot.yml, find the world-settings section. Under default, set merge-dropped-items to true and item-despawn-rate to 3000 (or lower, like 2000). This reduces the number of item entities on the ground, which are a common source of lag.
In spigot.yml, adjust entity-activation-range again (this is the Spigot version). Set monster to 24, animal to 16, and misc to 8. This works alongside the Paper settings—Paper’s settings override Spigot’s, but it’s good to keep them consistent.
In bukkit.yml, set ticks-per.animal-spawns and ticks-per.monster-spawns to 400 (default is usually 400). This is already optimal; don’t change it unless you know what you’re doing. The key is to ensure it’s not set to a very low number (like 1), which would cause constant spawn attempts.
Disable spawn-limits if you have a high player count. In bukkit.yml, under spawn-limits, set monsters: 50, animals: 10, water-animals: 5, ambient: 2. These are reasonable caps. If your server has 50+ players, consider lowering them further.
Restart your server and monitor the TPS. Use a plugin like spark (free) or run tps in the console. If TPS is consistently above 19.5, you’re good. If not, continue to the next steps.
Consider using paper-global.yml → timings. Set timings.enabled: true and timings.verbose: true. After a few minutes, run /timings report to get a detailed breakdown of what’s causing lag. This is the most accurate way to know what to optimize next.
Adjust max-entity-collisions in paper-world-defaults.yml. Set it to 2 (default is often 8). This limits how many entities can collide with each other per tick, reducing CPU load in crowded areas.
Set fix-climbing-bypassing-cramming-gamerule to false (if you don’t use the cramming rule). This is a minor optimization, but it can help in farms.

Common Mistakes

Copying settings from a YouTube video without understanding them. Server versions differ; what works for 1.20 might break 1.21.
Setting view-distance too low. While a low view distance (like 4) reduces lag, it also ruins the gameplay experience. Find a balance (6-8 is typical).
Disabling all redstone optimizations. Paper has a redstone-implementation setting. Setting it to alternate-current can help, but it may change redstone behavior. Test it on a small server first.
Ignoring the garbage collector (GC) settings. JVM flags like -Xms and -Xmx are critical. If you set them too low, the server will constantly GC, causing stutters. Don’t set them above the physical RAM available.
Changing too many settings at once. You won’t know which one helped or hurt. Change one or two, then test.

Tips

Use spark profiler. It’s the best tool to identify lag sources. Run /spark profiler for 10 minutes, then analyze the report.
Keep your server’s world size manageable. Pre-generating chunks (using a plugin like Chunky) prevents chunk generation lag when players explore new areas.
Limit the number of hoppers. Hoppers are notorious for causing lag. Use hopper-amount and hopper-transfer settings in paper-world-defaults.yml to adjust their behavior. Setting hopper-amount: 1 and hopper-transfer: 8 can help.
Monitor your CPU and RAM usage. If your CPU is constantly at 100%, you need to reduce entity counts or view distance. If RAM is maxed out, you need to allocate more or reduce the world size.
Regularly restart your server. Memory leaks can build up over time. A daily restart can keep things smooth.

Troubleshooting

Server won’t start after changes. Check the console for YAML errors. The most common cause is incorrect indentation. Revert to your backup and try again with one change at a time.

TPS is still low after optimization. Use /timings report to see what’s eating the most time. It might be a plugin, not the server. Disable suspicious plugins and test.

Players complain about mobs not spawning. You probably set entity-activation-range too low. Increase the values slightly (e.g., monsters to 32).

Redstone machines are broken. If you changed the redstone implementation, revert to the default. Also check if optimize-explosions is causing issues with TNT cannons—it shouldn’t, but test.

Server uses too much RAM. Reduce view-distance and entity-activation-range. Also consider lowering max-auto-save-chunks-per-tick to reduce memory spikes during saves.

Frequently Asked Questions

Q: What is TPS and why does it matter?
A: TPS stands for ticks per second. A normal server runs at 20 TPS. If it drops below 20, the server is lagging. Optimizing your config helps maintain 20 TPS.

Q: Will these optimizations work on a Spigot server?
A: Some will (like spigot.yml settings), but many are Paper-specific. If you’re using Spigot, consider switching to Paper for better performance.

Q: How often should I update Paper?
A: Every few weeks, or when a new version is released. Check the official Paper website for changelogs. Updates often include performance fixes.

Q: Can I use these settings on a modded server (Forge/Fabric)?
A: No, these are for Paper only. Modded servers have different optimization methods.

Q: What is the best view-distance for a lag-free server?
A: It depends on your hardware and player count. Start with 6 and adjust. If you have a powerful CPU, you can go higher (8-10).

Q: Do I need to change these settings for a small server (5 players)?
A: Probably not. Default Paper settings are already good for small servers. Only optimize if you’re experiencing lag.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →