Migrating from vanilla to Paper without breaking your world
Moving from vanilla to Paper is essentially one action: you stop the server, replace the server jar and start it again. Your world does not need converting, because Paper reads and writes exactly the same world format as Mojang's vanilla server. What does change is the configuration: after the first start there are four new files waiting for you (bukkit.yml, spigot.yml, config/paper-global.yml and config/paper-world-defaults.yml), and the defaults inside them can make redstone timings, mob spawning and existing farms behave differently from what you are used to.
Why does your world simply keep working?
Paper is a fork of Spigot, which in turn is a fork of the vanilla server. All three write the same region files to world/region, plus the same level.dat, playerdata and entity folders. There is no conversion step in between, no import and no migration screen.
In practice that means buildings, chests with their contents, player inventories, advancements, villages and your seed all stay exactly as they were, and server.properties, ops.json and whitelist.json carry over untouched as well. What Paper adds sits alongside all that rather than inside it: a set of configuration files and a plugins folder.
How do you migrate step by step?
- Stop the server cleanly. Use
/stopor the stop button in your panel, never a hard kill. Only then are all loaded chunks and player data written out in full. - Back up the entire server folder. So not only
world, but alsoworld_nether,world_the_endand your individual json files. At MC-Node automatic backups run as standard, but always take a manual one right before a migration: a backup five minutes old is worth more than last night's. - Grab the Paper build for exactly your version. If you are running 1.21 "Tricky Trials", still the most played version on Dutch servers, take a 1.21 build and do not jump straight to 26.1 or 26.2. A version upgrade and a software swap at the same time make troubleshooting needlessly hard.
- Replace the jar. Upload the Paper jar and point your startup command at it; in the Pterodactyl panel you do that under Startup. Leave the old vanilla jar in place, it is your fastest way back.
- Check your Java version. Minecraft 1.21 and newer runs on Java 21. An environment still on Java 17 will not start the server.
- Start up and read the console as it goes. This first start takes longer than usual, because all the configuration files are being created.
- Check things in the world itself. Join, type
/versionto confirm you are on Paper, and walk through your main builds, farms and portals. Then let the server run for half an hour before you send everyone back in, so you can see whether the TPS holds steady.
Which configuration files appear after the first start?
Vanilla only has server.properties. Paper adds four layers on top of that, each from a different lineage.
| File | Comes from | What it covers |
|---|---|---|
bukkit.yml | Bukkit | Spawn limits per mob category, spawn frequency, autosave interval, chunk cleanup |
spigot.yml | Spigot | Entity activation range, mob spawn range, item merging, hopper timings, view-distance |
config/paper-global.yml | Paper | Server-wide: chunk loading, network and logging settings, proxy support |
config/paper-world-defaults.yml | Paper | Per world: redstone implementation, per-player mob spawning, despawn distances, tick rates |
paper-world-defaults.yml acts as the default for all your worlds. If you want one world configured differently, you create a paper-world.yml in that world's folder; whatever is in there beats the defaults. On migration day itself, preferably change nothing at all.
Which vanilla mechanics can start behaving differently?
Paper gets most of its gains by simulating things that rarely matter either less often or less precisely. On most servers nobody notices. If your world leans on exact vanilla behaviour, it pinches in four places.
Redstone. Through misc.redstone-implementation in paper-world-defaults.yml, Paper lets you choose between the vanilla implementation and two faster alternatives (Eigencraft and Alternate Current). Those alternatives are cheaper in processing terms, but not identical in every edge case. Circuits that rely on the exact update order, such as instant repeaters, certain piston tricks and 0-tick contraptions, can stutter or seize up as a result.
Mob spawning. Paper can divide the mob cap per player instead of server-wide. That is fairer on a busy server, but it does change what a mob farm yields. On top of that sit the spawn limits in bukkit.yml and the mob-spawn-range in spigot.yml.
Entity activation range. Entities far enough away from a player get fewer ticks. Mobs in a farm then appear to freeze, villagers stop working and transport lines fall behind the moment you walk off. In practice this is where most of the "my farm is broken" reports come from.
Items and spawners. Loose items and experience orbs are merged across a greater distance than in vanilla: lovely for performance, annoying for farms that count items individually. And if nerf-spawner-mobs is on, mobs from a spawner no longer get any AI.
How do you restore that vanilla behaviour?
Almost all of it is a single configuration line. Work through one thing at a time, restart and test.
| What you notice | File | Where to look |
|---|---|---|
| Redstone reacts differently or locks up | config/paper-world-defaults.yml | misc.redstone-implementation set to vanilla |
| Mob farm yields less | bukkit.yml and paper-world-defaults.yml | Spawn limits and per-player mob spawning |
| Mobs and villagers freeze once you walk away | spigot.yml | entity-activation-range |
| Items clump together or vanish too fast | spigot.yml | merge-radius and the despawn settings |
| Spawner farm does nothing any more | spigot.yml | nerf-spawner-mobs |
| Hoppers visibly fall behind | spigot.yml | The hopper transfer and hopper check values |
Every piece of vanilla behaviour you put back costs you performance. With a handful of players that is no problem, on a busy survival server it is. Measure the effect with the spark plugin rather than guessing at it; the remaining dials are covered in our article on optimising your Minecraft server.
Can you go back to vanilla later?
Technically, yes, and usually without trouble. You stop the server, put the vanilla jar back and start up; the world loads fine, because the format never changed. Even so, the way back is not symmetrical.
What you lose are the plugins and everything they were keeping track of. Your LuckPerms ranks, EssentialsX homes, GriefPrevention claims and CoreProtect rollback history are all still on disk as files or databases, but they stop doing anything the moment vanilla is running. Protected regions are then simply no longer protected, and on a public server that shows within a day. On top of that, Paper-specific data is lost: extra values that plugins attached to items, entities or blocks, along with the configuration in the paper files. Vanilla does not know those fields and will not keep them.
If you were using a plugin that generated terrain, you can also end up with visible seams between old and new chunks. So keep a backup from just before the step back as well.
Why should you test on a copy first?
Because a migration rarely goes wrong on the jar, but on something you only notice days later: that one iron farm standing idle, a clock that no longer completes, a plugin that just about cannot cope with your version.
The cheapest approach is to download a copy of your world folder and run a Paper server on it locally. If you want to be closer to the real situation, network and plugins included, spin up a second server temporarily. A 2 GB test server on the budget line at Minecraft hosting from MC-Node costs EUR 2.20 per month, that is EUR 1.10 per GB, and you can cancel it again afterwards. If you are installing plugins at the same time, do that there first too; which ones you need for what is covered in our overview of the best Minecraft plugins.
When is Paper not the right choice?
Paper is the default choice for most servers, but not for all of them. If you want genuinely new blocks, items, mobs or dimensions, you need mods rather than plugins. Plugins run purely server-side on otherwise vanilla mechanics; mods are loaded by Forge, NeoForge, Fabric or Quilt and have to be on server and client in the same version. That is a different route, which we explain in our article on modpacks.
If you run a technical server where farms have to stay vanilla down to the tick, staying on vanilla is more honest than installing Paper and then reverting half of it. Do not look too quickly at the forks either. Purpur adds extra configuration options and optional features such as rideable mobs and adjustable mob AI, fully compatible with Paper plugins, but that is a step after Paper; Pufferfish sits between the two in intent. And Folia, the experimental multithreaded Paper, only makes sense with very high player counts spread across the map, and it breaks most existing plugins.
Frequently asked questions
Do I have to convert my world when I switch to Paper? No. Paper uses the same world format as the vanilla server, so region files, level.dat and playerdata stay usable unchanged; you only replace the jar. Do take a manual backup of the whole server folder beforehand.
Will my redstone machines still work after the switch? Usually, yes, but circuits that rely on the exact vanilla update order can behave differently. Through misc.redstone-implementation in config/paper-world-defaults.yml, Paper lets you choose between the vanilla implementation and two faster alternatives. Set it to vanilla if your clock or farm stops working.
Can I go back from Paper to vanilla? Yes, usually: put the jar back and start up, and the world loads fine. You do lose all plugins and what they did, so LuckPerms ranks, EssentialsX homes, GriefPrevention claims and CoreProtect rollback history stop functioning. Paper-specific data that plugins attached to items or entities does not come back.
Which Minecraft version should I pick for the migration? The same one you are running now. 1.21 "Tricky Trials" with the Trial Chambers, Vaults and the Mace is still the most played version on Dutch servers; after it came 26.1 "Tiny Takeover" and 26.2 "Chaos Cubed", and 26.3 is still in snapshots. Only move up once Paper is running steadily.
Do I need more RAM for Paper than for vanilla? No, a Paper server with plugins does not ask for more memory than the same vanilla world. It only gets genuinely heavy with modpacks: All the Mods 10 asks for at least 10 GB, 12 GB for a small group and 14 to 16 GB with five or more players.