How to Change Your Minecraft Server Version

Short answer

Take a backup, stop the server, change the version in the panel or replace the JAR, and start it. The world is upgraded in place on first start. That one-way change is why the backup is not optional: going back to the old version means restoring the backup.

A Minecraft server version is not a setting you toggle. The server software converts your world to the new format the first time it runs on the new version, and the old version cannot read what it wrote. Version changes are therefore forward-only, and the only way back is the copy you made before.

Most upgrades are uneventful and take a few minutes. The ones that go wrong do so for three reasons: no backup, a plugin that does not support the new version, or a modded server whose loader is missing. This guide covers all three.

Before you start

A backup you have tested, not just made
The current version noted, from the console or the panel
A maintenance window: the server must be stopped

1. Make and verify a backup

The conversion happens on first start and is not reversible from inside the server. A backup is therefore the only copy of the pre-upgrade world you will ever have, and it is worth ten minutes to make and verify.

Verify rather than assume: confirm the archive is not empty, and that it contains level.dat and the region folder. A backup that silently produced a 2 KB file is the failure mode that matters here.

what a complete backup contains

world/
  level.dat
  region/
  playerdata/
server.properties
plugins/
ops.json
whitelist.json

a manual backup, with the server stopped

cd /opt/mc/world
tar -czf ../backup-$(date +%F).tar.gz world server.properties plugins 2>/dev/null
tar -tzf ../backup-$(date +%F).tar.gz | head

2. Check your plugins and mods against the new version

Before changing anything, look at what will have to work on the new version. Every plugin needs a build that supports it, and a plugin compiled against old versions often logs warnings or fails to enable. Modded servers need the loader and the whole mod set for the new version.

This is the step that decides whether the upgrade is a restart or an evening. Read the changelog of each plugin you rely on, not just its download page.

the list to check, from the server folder

plugins/*.jar      each one needs a build for the new Minecraft version
world/mods/*.jar   a Fabric or NeoForge server needs matching loader and mods
world/datapacks/   usually fine, but data pack formats change too

3. Change the version, keeping the world

On a panel, the version is a field in the server settings: choose the new version, save, and start. On a self-hosted server, it is the JAR: download the build for the new Minecraft version, replace server.jar, and start.

The first start on the new version is where the conversion happens. It is slower than usual, and the console says so while it upgrades the world and its data. Do not interrupt it: killing the process mid-conversion is how a backup stops being optional.

If the server is a fork, take the fork's build for the new version, as in installing Paper.

self-hosted, swapping the JAR for the new version

java -Xms6G -Xmx6G -jar server.jar --nogui

server console, the first start on a new version

[12:31:00 INFO]: This server is running CraftBukkit version ... (Implementing API version 1.21)
[12:31:01 INFO]: Loading Minecraft 1.21.11
[12:31:02 INFO]: Preparing level "world" (using upgrade: true)
[12:31:09 INFO]: Done (12.402s)! For help, type "help"

4. Read the log, then play before you tell anyone

The startup log is where problems from an incompatible plugin or a data pack appear. Read the lines from the start, and pay attention to anything in ERROR or WARN that names a plugin.

Then play. Structures built with blocks or entities that changed in the new version can appear with missing data, and players notice that immediately. A short session before you hand the server back is how you find it while you still have the backup.

in game or console

/version
/plugins
/tps

5. If you need to go back, restore rather than downgrade

Going back means putting the old world back: stop the server, delete the current world folder, extract the backup, and start on the old version. There is no setting that converts a newer world back.

That is also why an upgrade should be done when the server is quiet rather than immediately before an event. If the players do not get on for a day, a rollback costs nobody anything.

Good to know

Paper, Spigot and Purpur each publish builds per Minecraft version, so the software and the version move together. Install Paper is the swap; this guide is choosing when.
Datapacks have their own format version and can need an update when Minecraft does. A data pack that stops working after an upgrade is usually a format change, not a bug.
Upgrade during a quiet period and tell your players it happened. Most Minecraft upgrades are invisible, and the ones that are not are much easier to explain in advance.
Restoring a backup is the reverse operation, and uploading a world covers moving one to a different server.

Common questions

Can I downgrade my Minecraft server version?

Not by changing the version. The new version converts the world to a format the old one cannot read, so going back means restoring a backup taken before the upgrade. Keep one until you are satisfied with the new version.

Will my world survive a version change?

Yes. The world, player data and inventories all carry over, and the server upgrades the format in place on first start. What can change is how new blocks and entities in existing structures appear until their data is regenerated.

How long does a version upgrade take?

A restart that takes seconds normally, and a slower first start while the world is upgraded. A large explored world takes longer. Do not interrupt it: stopping the process during the conversion is what turns a reversible change into a restore.

Do my plugins need updating too?

Usually yes. Each plugin needs a build that supports the new version, and several need their dependencies updated in the same restart. Check the changelogs before changing the version so the two happen together.

Will my players need a new Minecraft client?

Yes. A server on 1.21.x refuses clients on older versions, and the error names the version it wants. Everyone has to update their launcher before they can join.

Sources

Official documentation this guide was checked against.

Rather not run this on your own machine? PufferHost gives every player a free Minecraft server with 3 GB of RAM and 10 slots. Create a free server.