How to Install Purpur on a Minecraft Server

Short answer

Purpur installs exactly like Paper: stop the server, replace server.jar with the Purpur build for your Minecraft version, and start it. Purpur's own documentation says to follow the Paper getting-started guide, because it is a drop-in replacement with no extra steps.

Purpur exists because some gameplay conveniences are worth having and are not worth a plugin dependency: rideable mobs, per-world mob caps, sleeping through the night regardless of who is in bed, and the ability to disable specific gamerules. All of them are off by default and live in one file.

That makes the install a file swap and the decision a small one. This guide covers the swap, the file you will want afterwards, and the one compatibility check worth doing first.

Before you start

Java 21 installed
File access to the server folder
A backup of the world, as for any server change

1. Check your plugins before you switch

Purpur implements the same plugin APIs as Paper, so almost every Paper plugin runs on it unchanged. The exceptions are plugins that check the server brand by name and refuse to start on anything else.

If your server already runs plugins, this is the step that decides whether the switch is boring or annoying. A minute spent on the plugin list now is cheaper than a broken server later.

Datapacks and data packs work the same way: they are vanilla content, so anything that worked on Paper works here. What changes between the forks is only the server-side configuration and the commands each one adds.

If you are coming straight from vanilla rather than from Paper, install Purpur instead of installing Paper first. The procedure is identical, and there is no reason to visit the middle fork.

in game or console, on your current server

/plugins
/version <plugin_name>

2. Stop the server and download the right build

Stop the server completely, then take the Purpur build for the Minecraft version you run. Purpur's versions are listed the same way Paper's are: a Minecraft version with the newest release first, plus the older versions it still supports.

Take the newest build for your version rather than the newest build overall, for the same reason as Paper: builds are tied to a Minecraft version. Purpur names its files after the Minecraft version they target, so the download page and the file name both tell you which is which.

Keep the file name you started with out of it: you will rename it to server.jar in the next step, and naming it after the fork only helps if you are keeping a library of builds.

where the builds live

https://api.purpurmc.org/v2/purpur
  -> versions: 1.21.x, 1.20.x, ...
  -> purpur-<minecraft version>.jar

The project page also lists which version is current.

3. Swap the JAR, keeping the name

Delete the old server.jar and put purpur-<version>.jar in its place renamed to server.jar. Everything else stays: the world, server.properties, plugins and access lists are read by Purpur exactly as the previous software wrote them.

Start it. On the first boot Purpur writes purpur.yml alongside Paper's configuration files, and the console says which version is loading.

server root, after the swap

java -Xms6G -Xmx6G -XX:+UseG1GC -jar server.jar --nogui

server console, the Purpur boot

[12:31:02 INFO]: Loading Minecraft 1.21.11 with Purpur 1.21.11
[12:31:05 INFO]: Done (9.240s)! For help, type "help"

4. Confirm, then open purpur.yml

/version prints Purpur as the server brand, and /plugins lists your plugins with the same green and red colouring as Paper. That is the whole verification.

Then open purpur.yml. Every option is off, so the server behaves exactly like Paper until you change something. The file is commented, and the sections are grouped: global behaviour, blocks, mobs, experience and a per-world worlds: block.

Two options decide more conversations than the rest. blocks.disable turns individual mechanics off across the server, such as fire spread, grass spread or leaf decay, which is the operational change people usually want. The worlds: section sets mob caps, gamerules and sleep rules per world, which is how an arena and a survival overworld stay different on one server.

purpur.yml (excerpt with defaults)

allowSleepingOutsideTimeZone: false
blocks:
  disable:
    fireTick: false
    grassSpread: false
    leafDecay: false
mobs:
  # per-world mob caps live under worlds:
experience:
  join:
    players:
      - join-message-radius: 0

5. Play a session before you change anything

Run a normal session with the plugins you rely on and check the startup log for warnings. Paper plugins that call deprecated APIs log them here too, which is information worth having whether or not you stay on Purpur.

Purpur also adds its own commands, and they are documented separately from Paper's: a /purpur command covers the features its fork adds, including the reload for its own configuration. It is not in Paper, so a script written for Paper that calls /purpur only works here.

Then decide whether you want any of the features at all. Plenty of servers run Purpur for months with purpur.yml untouched, which is a perfectly good outcome.

in game or console

/version
/plugins
/tps

Good to know

Purpur tracks Paper upstream, so new Minecraft versions arrive for both at about the same time.
Paper vs Purpur sets out what the fork adds and when it is worth it, which is worth reading before you enable anything.
Purpur features can be set per world through the worlds: section, so a creative arena can have them while a survival overworld stays strict.
Keep the old JAR outside the server folder until you are satisfied. Rolling back is then a copy rather than a download.

Common questions

Is Purpur harder to install than Paper?

No. Purpur's own documentation says to follow the Paper getting-started guide, because it is a drop-in replacement: same JAR swap, same command, same world files, and one extra configuration file afterwards.

Will my Paper plugins work on Purpur?

Almost all of them, because Purpur implements the same plugin APIs. The exceptions check the server brand by name and refuse to start; check your plugin list before switching if that matters to you.

Does Purpur change gameplay?

Not by default. Every feature is off in the default purpur.yml, so a fresh Purpur server behaves like Paper until you change a line.

Should I run Purpur or Paper?

Purpur if you want one of its features without a plugin, Paper if you would rather keep one fewer file. The comparison guide covers the decision in more detail.

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.