Moving a live Minecraft server from Spigot to Paper is one of the highest-return upgrades a Java edition owner can make, and it is also one of the easiest to get wrong. This guide exists to help you do it safely: keep your players online, keep your plugins working, and keep a clear path back if something misbehaves. Whether you run a ten-player SMP or a network pushing hundreds of concurrent users, the same careful process applies.

This article is written for server owners, administrators, plugin developers, and staff who are comfortable editing configs and dropping JARs into a plugins folder but want a battle-tested migration process rather than guesswork. The recommendations below come from running Spigot and Paper builds side by side on staging hardware, profiling both with spark, reading the Paper project documentation, and reviewing how plugin compatibility actually breaks in practice.

By the end you will know exactly why Paper is worth the move, how to back up and stage the change, which plugins are risky and why, how configs and worlds carry over, how to verify performance after the switch, and how to roll back in minutes if you need to. If you are brand new to server JARs in general, read our [Beginner’s Guide to Minecraft Server JARs] first, then come back here for the migration specifics.

Why Paper Is Worth Leaving Spigot For

Paper is a high-performance, open-source fork of Spigot that has been the de facto standard for Java servers for years. It is not a different game and it is not a different plugin platform; it is a drop-in server JAR that keeps the Bukkit and Spigot plugin APIs intact while fixing thousands of issues and optimizing the hot paths that Spigot leaves alone. You can read the full feature list and usage guidance in the Paper documentation and grab current builds from papermc.io/downloads.

The three reasons that matter most during a migration are performance, bug fixes, and an actively maintained API.

• Performance: Paper reduces entity ticking cost, optimizes chunk loading and saving, and adds async chunk handling. On busy worlds these wins translate into lower tick times and more headroom before you hit the tick budget.
• Bug fixes: Paper patches long-standing vanilla and Spigot exploits, duplication bugs, and crash vectors. Many of these fixes never land in Spigot, which often lags behind on non-security patches.
• Updated API: Paper tracks new Minecraft versions quickly and extends the Bukkit API with modern events and helpers. Plugin developers increasingly target Paper-first features, so staying on Spigot means slowly losing access to updates.

Because the source is public, you can verify exactly what changes before you commit. The Paper GitHub repository publishes every patch, and each release notes the upstream Minecraft version it is built against. That transparency is part of why so many production networks standardize on it.

Before You Touch Anything: Backup and Staging Plan

A migration without a backup is not a migration, it is a gamble. Do this work on a copy of your server, never on the live instance, until the very final cutover. The goal is a fully tested Paper server that behaves identically to your Spigot server, ready to swap in during a maintenance window.

Step 1: Take a Full, Verifiable Backup

• Stop the server cleanly and let it finish saving before you copy anything.
• Archive the entire server directory: JAR, plugins with their configs and data, world folders, server.properties, and any custom scripts.
• Keep one off-site copy. An archive on the same disk is not a backup.
• Record your current Spigot build number and your exact plugin list with versions, so you can reproduce the baseline.

Step 2: Stand Up a Staging Copy

Copy the archive to a separate staging directory or machine and run the existing Spigot server there first. Confirm it starts and behaves normally, so you know the baseline is healthy before you change the JAR. Then, and only then, swap in Paper on the staging copy. This isolates the migration as the single variable you are testing.

Step 3: Know Your Rollback

1. Keep the Spigot JAR and the original plugin versions in a known folder.
2. Snapshot the world folders before the cutover so you can restore them in one move if a plugin corrupts data.
3. Write down the exact stop, swap, and start command sequence so rollback is a copy-paste operation, not improvisation.
4. Announce a maintenance window to players so a rollback is invisible rather than a surprise.

Plugin Compatibility: The Real Risk

The plugin platform does not change when you move to Paper, so the vast majority of plugins built against the Bukkit and Spigot APIs work without modification. Where migrations break is almost always one of three things: plugins that reach into server internals, plugins that are version-locked, and plugins that are simply abandoned. Search the SpigotMC resource directory for each of your plugins and check the last update date and stated compatibility.

NMS, Reflection, and Version-Locked Plugins

NMS means the plugin uses internal Minecraft server classes (net.minecraft.server) instead of the public API. Because those internals change with every Minecraft version and are remapped differently between Spigot and Paper, NMS plugins are the number one cause of migration failures. Reflection-based plugins that fish for internal fields are nearly as fragile. Version-locked plugins explicitly state they support only certain versions and often refuse to load outside that range.

If you depend on an NMS or reflection plugin, check whether a Paper-native build or a modern replacement exists before you migrate. The good news is that most performance and utility plugins now ship Paper-friendly versions, and many features that once required NMS (custom blocks, mob AI tweaks, region handling) are covered by maintained projects.

How to Test Plugin Compatibility Safely

• Start the staging Paper server and read the console for red stack traces and unsupported warnings.
• Run each plugin command and simulate its typical workload, not just its load time.
• Check plugins with databases (permissions, economy, stats) and confirm their data still reads correctly.
• For permissions specifically, validate your setup against a guide like [LuckPerms Guide: Advanced Permissions] to confirm groups, tracks, and inherited nodes behave as expected.

Config and World Migration

Your worlds and most configs carry over directly because Paper reads the same formats Spigot does. Still, a few areas deserve attention.

• Worlds: Copy the world, world_nether, and world_the_end folders intact. Paper upgrades region data on first start; keep the pre-upgrade backup in case you need to revert.
• paper.yml and new configs: Paper adds its own config (paper.yml, later the split config files under config/). It generates defaults on first run. Review performance and anti-exploit settings rather than copying Spigot settings blindly.
• server.properties: Safe to copy as-is, but re-check view-distance and simulation-distance, which Paper can often raise for the same CPU cost.
• Plugin data: Copy each plugin folder, not just the JAR. This preserves ranks, homes, warp points, and economy balances.

Vanilla-Behavior Flags Matter

Paper ships with tweaks enabled by default, and a handful of them change gameplay. If you want maximum parity with vanilla or Spigot behavior, review the settings that affect redstone, mob spawning, and item merging. Turning the aggressive tweaks off gives you Spigot-like behavior while keeping the performance improvements; leaving them on gives you the Paper experience most players now expect. Decide deliberately rather than accepting whatever the defaults happen to be.

The Step-by-Step Switch

1. Complete a rehearsal on staging until login, worlds, and every plugin behave correctly.
2. Announce and open a maintenance window; warn players to log out.
3. Stop the live server cleanly and take a fresh backup of the production world and plugin data.
4. Replace the Spigot JAR with the matching Paper JAR, keeping the Spigot JAR nearby.
5. Start the new server and watch the console for errors, warnings, and deprecation notices.
6. Run smoke tests: log in, teleport, use each plugin command, and check the economy and permissions.
7. Open the server to players and monitor tick times closely for the first few hours.

Keep the cutover boring. If a critical plugin fails on the live server, stop, restore the backed-up world and plugin data, put the Spigot JAR back, and start again. Because you rehearsed, this should take minutes, not hours.

Verifying With spark and Timings

After the switch, measure instead of assuming. Paper recommends spark for profiling, and it is the tool you want in place of the old timings system, which Paper removed. Run a spark profiler during a busy period and read the results.

• Use /spark profiler start, let it collect for a few minutes under load, then /spark profiler stop and inspect the report.
• Look at tick durations: a healthy server stays well under 50 ms per tick (20 TPS). Paper should reduce this versus your Spigot baseline.
• Identify the plugin or system consuming the most time and optimize or replace it.
• Track TPS and MSPT over the first week to confirm the improvement holds as player counts grow.

If you tune your JVM at the same time, align your flags with current best practice. Our [Aikar’s Flags Explained] guide and the [ZGC vs G1GC comparison] cover the collector and flag combinations that pair best with Paper builds.

Compatibility Checklist

Run through this table before you call the migration done. It maps each risk area to what to check and the likely verdict.

Benefits vs Caveats

Paper is the right default for almost every Java server, but an honest look at both sides keeps expectations realistic.

• Benefit – performance: Lower tick times and better scaling under load.
• Benefit – stability and security: Regular bug and exploit fixes Spigot often skips.
• Benefit – active API: Fast support for new Minecraft versions and modern plugin features.
• Benefit – tooling: First-class spark support and clear documentation.
• Caveat – default tweaks: Some Paper defaults change gameplay; review them if you want vanilla parity.
• Caveat – NMS plugins: Internals-based plugins may need replacement or a Paper-native build.
• Caveat – learning curve: New config files and settings take an afternoon to understand.
• Caveat – timing tool changes: The old timings command is gone; you must adopt spark.

Common Mistakes and Expert Tips

Most failed migrations share the same handful of errors. Avoid these and you will have a smooth cutover.

• Migrating on the live server: Always rehearse on a copy. The live instance is for the final, tested swap only.
• Skipping the world backup: Paper upgrades region data on first start. Without a snapshot you cannot cleanly revert.
• Copying only plugin JARs: You lose ranks, warps, and balances. Copy the plugin data folders too.
• Ignoring the console: Silent deprecation warnings become crashes later. Read every startup line.
• Assuming a version-locked plugin is fine: Check its changelog and stated support range explicitly.
• Not profiling afterward: You cannot prove the win or find the next bottleneck without spark data.

Expert tip: run Paper on staging for a full week with a few trusted players before the production cutover. Real player behavior surfaces plugin edge cases that a five-minute smoke test never will. Pair that with reading the release notes for each build so nothing surprises you on switch day.

Frequently Asked Questions

Conclusion: Make the Move the Safe Way

Migrating from Spigot to Paper does not have to be risky. Back up everything, rehearse on a copy, check your NMS and version-locked plugins first, carry over your plugin data, and verify the result with spark. Do that, and the switch becomes a routine upgrade that buys you better performance, stronger security, and an API that keeps pace with Minecraft itself.

Ready to start? Grab the current build from papermc.io/downloads, read the Paper documentation for your version, and set up your staging copy today. If you want to go further, explore Purpur once you are comfortable on Paper – it builds on the same foundation with even more configuration options.