Migrating from Paper & updates
Move an existing Paper server to NusaSpigot, update to a newer release, and know what to check before you switch back.
On this page
NusaSpigot is a drop-in Paper fork, so your existing worlds, server.properties, paper-global.yml, spigot.yml and plugins/ folder carry over as they are. This page shows the safe order of steps.
Moving from Paper to NusaSpigot
- Stop the server cleanly with
stopand wait until the process has fully exited. - Make a full backup of the whole server folder (worlds,
plugins/and config files) and keep a copy outside the live folder. - Copy
NusaCore.jarandnusa-license.propertiesfrom your download into the server folder. - Point your start script or panel to
NusaCore.jarinstead of the Paper JAR. The start commands are in Quick start & installation. - Start the server. Choose your Minecraft version when NusaCore asks. NusaSpigot creates
nusa-global.ymlandnusa-world.ymlwith safe defaults next to your Paper configs. - Check health with
nusa statusandnusa doctorin the console.
Use the same Minecraft version as your old Paper server (for example 1.21.11). Moving to a newer Minecraft version at the same time is a separate step; test it on a copy first.
Updating NusaSpigot
If you already run NusaCore, updating is one step:
- Restart the server.
- NusaCore downloads and verifies the newest release for your Minecraft version by itself.
Your existing configuration values are kept. New settings that are missing from your files use their safe defaults. A release note may also recommend replacing NusaCore.jar with the newer one from the download page; do that while the server is stopped.
Coming from an older build started directly
If you still start an older NusaSpigot build directly as a server JAR (for example NusaSpigot-v1.2-1.21.11.jar), switch to NusaCore:
- Stop the server and make a backup.
- Put
NusaCore.jarandnusa-license.propertiesfrom the current download into the server folder. - Change the start command to
java -jar NusaCore.jar --nogui. Keep your memory flags. - Start the server and choose your Minecraft version when asked.
Your worlds, plugins and nusa-global.yml stay as they are.
Moving a license to Minecraft 26.2
A license is locked to one Minecraft version when it is first used. To move an existing license to 26.2, open a support ticket. Remember that 26.2 needs Java 25, and plugins that use server internals with Spigot mappings need a 26.2 update from their author. See Plugin compatibility.
Important: region compression and switching back
feature-flags.region-file-compression is true by default. What this means for you:
- Existing Paper chunks load normally. Nothing is converted all at once on startup.
- Newly saved chunks use Zstandard (Zstd) compression. Plain Paper or vanilla cannot read those chunks directly.
- Still evaluating? If you might go back to plain Paper without restoring your backup, turn it off before players join:
feature-flags:
region-file-compression: falseKeep your pre-migration Paper backup until you are happy with the switch.
Next steps
- Learn the everyday tools in Commands & in-game panel.
- Pick a ready-made profile in the Configuration guide.