How to Make a Purpur Minecraft Server (and Paper vs Purpur)

What Purpur is

Purpur is a Java Edition server built on top of Paper. Its documentation describes it as a drop-in replacement for Paper, which means that nothing has to change in your plugins or worlds when you switch. It keeps Paper's performance and adds a large number of extra options: tweakable mob behaviour, gameplay tweaks and server features, mostly configured in a file called purpur.yml.

Paper or Purpur?

• Choose Paper if you want the most widely used, most tested base and do not need extra options. Most plugin authors test on Paper first.
• Choose Purpur if you want fine control over gameplay details without writing plugins, for example a technical survival server or one that wants a few vanilla rules changed.
• Both run the same plugins. Switching either way later is easy.
• More options means more ways to change how the game feels. Players who expect vanilla behaviour can be confused by unexpected changes, so change settings one at a time and tell your players what you changed.

Install Purpur from scratch

The steps are the same as for Paper. Follow our Paper guide for the full explanation of Java, the EULA, server.properties and plugins, and make these two changes:

1. Download the Purpur jar for your Minecraft version from purpurmc.org. Only use the official site.
2. Save it in an empty folder as purpur.jar and use the same start command with the new file name.

java -Xms4G -Xmx4G -jar purpur.jar --nogui

Purpur needs the same Java version as the Paper build for that Minecraft version. Paper's documentation lists Java 21 for 1.20 to 1.21.11 and Java 25 for 26.1 and newer. Check the Purpur download page too, because requirements change with new Minecraft versions.

Switch an existing Paper server to Purpur

If something goes wrong, stop the server, restore the backup and start Paper again. Moving between Paper and Purpur on the same Minecraft version is safe. Moving to a newer Minecraft version at the same time is a bigger change, so do those as two separate steps.

1. Stop the server and make a full backup of the whole folder.
2. Download the Purpur jar for the same Minecraft version as your current Paper jar.
3. Put it in the server folder and change your start script to use the new jar name.
4. Start the server. Purpur creates purpur.yml and keeps your world, plugins and server.properties.
5. Watch the console for errors, then test with a player account before announcing that the server is back.

Configure purpur.yml safely

After the first start you will find purpur.yml in the server folder. It is long and heavily commented. Settings that apply to the whole server sit near the top, and per-world options live under a world-settings section where a default entry applies to every world and a world's own name can override it.

A safe way to work:

1. Read the official Purpur documentation for the option you want. Do not guess at option names.
2. Change one setting at a time and restart.
3. Test in the game. If you do not like the result, change it back.
4. Keep a copy of your edited purpur.yml with your backups.

Be careful with settings copied from random guides. They are often written for older versions, and a setting that does not exist any more is silently ignored or can cause errors.

Plugins, Geyser and ViaVersion

Plugins written for Paper, Spigot and Bukkit run on Purpur. Geyser, Floodgate and ViaVersion all work the same way as on Paper: put the jar in plugins and restart. See our Geyser and Floodgate and ViaVersion guides for the details.

Troubleshooting

• "Unsupported class file major version": Java is too old for this build.
• A plugin works on Paper but not on Purpur: check the plugin's page for known Purpur issues, and test with the setting you changed turned off.
• Gameplay feels different after switching: compare your purpur.yml against defaults, since each option has a documented default.
• The server will not start after an update: restore your backup and check that the jar matches your Minecraft version.

Frequently asked questions