How to Migrate from Vanilla to Paper Without Losing Your World

Why Migrate Vanilla to Paper?

Vanilla Minecraft servers work fine for a few friends, but once you want serious performance, plugin support, or configurable anti-cheat, you need Paper. Paper is a drop-in replacement for the vanilla server jar that adds hundreds of performance optimizations, a plugin API (Bukkit/Spigot/Paper), and granular configuration options, all while keeping full compatibility with vanilla clients. Players connect the same way; they do not need to install anything. The decision to migrate vanilla to Paper Minecraft is the single biggest upgrade most server owners make.

The good news: migrating is straightforward and your world, player data, and ban lists all carry over perfectly. This guide walks through every step.

Before You Start: Back Up Everything

This is non-negotiable. Before you touch anything, make a complete backup of your server directory:

tar -czf ~/vanilla-backup-$(date +%Y%m%d).tar.gz /opt/minecraft

See our backup guide for more robust strategies. If anything goes wrong during migration, you can restore from this backup and be back to exactly where you started.

Step 1: Download the Paper Jar

Go to papermc.io/downloads and download the Paper build matching your current Minecraft version. If you are on 1.21.4 vanilla, get Paper 1.21.4. Do not change Minecraft versions and server software at the same time, that introduces two variables and makes troubleshooting harder.

cd /opt/minecraft
# Keep the old jar as a fallback
mv server.jar vanilla-server.jar
# Download Paper
curl -o server.jar https://api.papermc.io/v2/projects/paper/versions/1.21.4/builds/LATEST/downloads/paper-1.21.4.jar

Step 2: Understand the World Folder Differences

This is the step most guides skip, and it is the one that causes the most confusion when you migrate vanilla to Paper Minecraft. Vanilla and Paper store dimensions differently:

Vanilla Structure

world/
├── region/          (overworld chunks)
├── DIM-1/
│   └── region/      (nether chunks)
├── DIM1/
│   └── region/      (end chunks)
├── level.dat
├── playerdata/
└── data/

Paper/Bukkit Structure

world/
├── region/          (overworld chunks)
├── level.dat
├── playerdata/
└── data/
world_nether/
├── DIM-1/
│   └── region/      (nether chunks)
world_the_end/
├── DIM1/
│   └── region/      (end chunks)

Paper splits each dimension into its own top-level folder. When you first start Paper with a vanilla world, Paper handles this conversion automatically. It detects the vanilla structure and separates the nether and end into their own directories. You do not need to move files manually, just make sure you have that backup in case something unexpected happens.

Step 3: Review server.properties

Your existing server.properties file works with Paper without changes. Paper reads the same file and respects all vanilla settings. After the first launch, Paper will create additional configuration files:

• paper-global.yml, server-wide Paper settings
• paper-world-defaults.yml, per-world default settings
• bukkit.yml, Bukkit-layer configuration
• spigot.yml, Spigot-layer configuration
• config/paper-world-defaults.yml, Paper world-specific overrides

Start with the defaults and tune later. Our Paper.yml settings explained guide covers every important option.

Step 4: First Launch

Start the server exactly as before, just pointing to the new jar:

java -Xms4G -Xmx4G -jar server.jar --nogui

Watch the console output carefully during this first boot. Paper will:

1. Generate the new config files (paper-global.yml, bukkit.yml, spigot.yml)
2. Convert the world folder structure (splitting nether and end)
3. Load the existing world, player data, advancements, and statistics

Verify everything works: log in, check your inventory, visit the nether and end, confirm that placed blocks and builds are intact.

Step 5: Install Your First Plugins

The entire reason to migrate vanilla to Paper Minecraft is plugin support. Paper is compatible with Bukkit, Spigot, and Paper plugins. Drop .jar files into the plugins/ folder (created automatically on first launch) and restart.

Essential first plugins:

• EssentialsX, homes, warps, kits, economy, and dozens of utility commands
• LuckPerms, permission management with a web editor
• Spark, performance profiling (see our Spark guide)
• CoreProtect, block logging and rollback for grief recovery

Step 6: Tune Paper Settings

Paper ships with conservative defaults that prioritize vanilla parity. For better performance, you will want to adjust simulation distance, entity activation ranges, and mob spawn limits. Our Paper.yml settings guide covers the most impactful changes, and the JVM flags guide covers memory and garbage collection tuning.

What About Vanilla Features and Redstone?

Paper fixes many vanilla bugs and exploits, which occasionally changes behavior that some players rely on. The main areas to watch:

• TNT duplication, disabled by default in Paper. Re-enable in paper-global.yml if your players use TNT dupers.
• Sand duplication, also patched. Configurable in Paper's settings.
• Redstone, Paper uses an optimized redstone algorithm that behaves identically for 99% of builds. Extremely complex quasi-connectivity exploits may behave differently.

If vanilla-exact behavior is critical, check paper-global.yml and paper-world-defaults.yml for the unsupported-settings section where you can re-enable patched exploits.

Rollback Plan

If something goes wrong, rolling back is simple:

# Stop the Paper server
# Restore your backup
tar -xzf ~/vanilla-backup-*.tar.gz -C /
# Start with the vanilla jar
java -Xms4G -Xmx4G -jar vanilla-server.jar --nogui

The vanilla server will ignore the extra Paper config files and the world folder structure will work as-is (Paper does not delete the original dimension folders during conversion).

Summary

Migrating from vanilla to Paper takes about 10 minutes: download the jar, start the server, and let Paper handle the world conversion automatically. Your world data, player inventories, advancements, and statistics all carry over without any manual file editing. Once running, tune the new config files and install plugins to unlock Paper's full potential. For a full comparison of server types, see our server types guide.

Want to just play? Join Astroworld MC, IP play.astroworldmc.com, Java + Bedrock.