# Purpur: a Paper fork that turns server behaviour into config

> Purpur is a drop-in replacement for Paper that exposes gameplay and mechanics as server-side settings. It suits admins who want to change vanilla behaviour without writing plugins, and it is the wrong choice for anyone who needs a vanilla or Paper-identical server.

**PurpurMC/Purpur** — Purpur is a drop-in replacement for Paper servers designed for configurability, and new fun and exciting gameplay features.

- Repository: https://github.com/PurpurMC/Purpur
- Website: https://purpurmc.org
- Stars: 2,418 · Forks: 505
- Language: Java
- License: MIT
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/purpurmc-purpur

## What Purpur changes about running a Paper server

Paper already sits between vanilla Minecraft and the plugin ecosystem, and Purpur sits one layer above Paper. The README describes the project as "a drop-in replacement for Paper servers designed for configurability, and new fun and exciting gameplay features." That sentence is the whole pitch, and it is also the constraint: Purpur is not a new server platform, it is Paper with more switches.

The practical effect is that decisions normally made by a plugin become decisions made by a config file. Whether a specific mob behaviour is on, whether a specific mechanic is altered, whether some vanilla quirk is preserved or removed: those are the kinds of choices Purpur moves into server configuration. For an admin running a small survival server, that reduces the number of plugins in the folder and the number of update cycles to track. For an admin running a large network with bespoke plugin code, it mostly means more config surface to reason about.

The audience is narrow and specific. If you are happy with Paper defaults, Purpur gives you nothing. If you want one or two mechanics changed and would otherwise install a plugin to do it, Purpur is the cheaper option, because a config key does not break when Minecraft updates the way a plugin can.

## How Purpur is built and why the repository has three modules

The top-level layout tells you most of what you need to know about the architecture. There are three source directories: purpur-api, purpur-server and purpur-checkstyle. Alongside them sit build.gradle.kts, settings.gradle.kts, gradle.properties and the Gradle wrapper, plus build-data/ and scripts/.

purpur-api is the interface layer that plugins compile against. purpur-server is the implementation. The split matters because it is the same pattern Paper and Spigot use: a plugin that depends on the API can be built without pulling in the whole server. If you write a plugin and want to detect whether the server is Purpur before touching a Purpur-only setting, purpur-api is where that capability lives.

purpur-checkstyle is a build-time module, not a runtime one. It exists so that contributed code conforms to the project's formatting rules before it is merged. build-data/ and scripts/ support the build and release process rather than the running server. The MC_UPDATE_TODO.txt file at the repository root is a plain checklist for the work each new Minecraft version requires, which is a candid signal about the maintenance shape of the project: every upstream Minecraft release starts a port, and that file tracks it.

The default branch is ver/26.3, and the build badge in the README points at a versioned branch rather than a single trunk. That is the standard fork arrangement. Development happens per Minecraft version, and the branch you build from determines which game version you get.

## Installing Purpur and getting a server to start

Purpur is distributed as a server jar. The README links its downloads badge to purpurmc.org/downloads/, and that page is where the project says to get the build. The README itself does not walk through installation, and the repository files do not contain a start command, a jar filename, a flag or a port, so this section describes the sequence without inventing one.

Get the build from the downloads page, place the jar in an empty directory, and start it once. The first run generates the configuration files, including the Purpur-specific ones, and then exits because the EULA has not been accepted. This is the same first-run behaviour Paper and Spigot have.

After that first run, the directory contains eula.txt, server.properties, the bukkit, spigot, paper and purpur config directories, and a plugins folder. Open eula.txt and set the agreement flag to true, then start the server again. The exact java invocation is whatever your host or your existing Paper setup already uses; Purpur does not change it.

The second start should reach a "Done" line and open the default port from server.properties. If it does not, the usual causes are a Java version mismatch with the Minecraft version you downloaded, or a port already in use.

For a first real change, go into the purpur configuration directory that the first run created and edit the settings file there. The exact keys are version-dependent and the README does not enumerate them, so read the comments in the generated file rather than copying keys from a blog post; a key from an older Minecraft version may not exist in your build. Restart the server after editing, because these settings are read at startup.

## Where Purpur is the wrong tool

The drop-in claim cuts both ways. Because Purpur is Paper plus changes, any behaviour it alters is behaviour that differs from Paper and from vanilla. If your server hosts technical players who build redstone contraptions against exact vanilla tick behaviour, or if you run a competitive mode where players expect parity with a reference server, a configurable fork is a liability rather than a feature. You would be spending time proving that the settings you left alone really are leaving behaviour alone.

There is a second, structural limitation. Purpur inherits Paper's release cadence and Paper inherits Minecraft's. When Minecraft ships a version, Purpur has to wait for Paper, then port its own changes on top, and MC_UPDATE_TODO.txt at the repository root exists precisely because that port is manual work. A server that must be on the newest Minecraft version on day one is better served by Paper, which is upstream and therefore closer to the front of that queue.

The third case is plugin-driven servers. If everything you want to change is already handled by a plugin you trust, adding Purpur adds a fork to your update path without removing anything. The trade is only worth making when Purpur's config replaces plugins you would otherwise run.

## Purpur vs Paper: the actual difference

The comparison is not about performance or stability, and the README makes no such claim. It is about where configuration lives.

Paper is the upstream project. It is the base that Purpur patches, and it defines the plugin API, the config structure and the release schedule that Purpur follows. Paper's own settings cover a broad set of server behaviours, and for many admins Paper's config is already more than they will ever touch.

Purpur takes Paper and adds a further layer of gameplay settings on top, which is what the description means by "configurability, and new fun and exciting gameplay features." The difference in approach is therefore additive rather than competitive: Purpur is a superset in configuration terms and a downstream in maintenance terms. Choosing between them is choosing whether the extra settings are worth being one step behind Paper on every Minecraft release.

If you are deciding between Spigot and Purpur, the gap is wider. Spigot is further upstream still and does not carry Paper's optimisations or Paper's config surface. Purpur is not a Spigot replacement in the same sense; it is a Paper replacement, and Paper is the thing it is measured against.

## Licence, forks and the cost of staying current

Purpur is MIT licensed, and the LICENSE file is at the repository root. MIT is permissive: it allows modification, redistribution and commercial use, and it requires that the licence text and copyright notice travel with copies. For a server admin this is mostly a non-issue, because you are running the jar rather than redistributing it. For anyone packaging Purpur into a hosted product or a modpack, the obligation to keep the notice is the one to check. This is a description of the licence text, not legal advice; read LICENSE and, if you are redistributing, get your own review.

The upgrade cost is the part that is easy to underestimate. Purpur's default branch is versioned (ver/26.3), so upgrading the server means moving to a different branch of the project, not pulling the latest commit on one trunk. Your config files carry across in the common case because Purpur is a drop-in replacement for Paper, but any key that a new Minecraft version removed or renamed will be ignored or regenerated, and the README does not document a rollback procedure for config changes. The practical consequence is that you should keep the previous jar and the previous config directory until you have confirmed the new build starts cleanly and your players report nothing broken.

Maintenance is active in the narrow sense that matters here: the repository is not archived, and the last push was on 2026-09-27. That tells you the project is being worked on now. It does not tell you how quickly a given Minecraft version will be supported, and the README does not publish such a timeline.

## Conclusion

Adopt Purpur if you already run Paper and want vanilla mechanics exposed as configuration instead of as plugins, and if you can carry the cost of tracking Paper upstream. Do not adopt it if you need a byte-identical Paper or vanilla server, or if your players depend on vanilla parity for redstone and mob behaviour. Before switching, verify three things: that a Purpur build exists for your Minecraft version, that your existing Paper config files survive the drop-in, and that the settings you intend to flip are documented for your build rather than only described in the source.

## FAQ

### How do I install a Purpur Minecraft server?

Download the server jar from the downloads page linked in the README, place it in an empty directory, and start it once. That first run generates the config files and exits; set eula=true in eula.txt and start it again.

### How do I set up Purpur?

Setup is the same as Paper: accept the EULA, then edit the generated config directories, including the purpur directory created on first run. Purpur settings are read at startup, so restart the server after changing them.

### Is Purpur better than Paper?

The README describes Purpur as a drop-in replacement for Paper built for configurability, so it adds settings rather than replacing Paper's approach. It is downstream of Paper, which means it follows Paper's release schedule rather than leading it.

### Which is better, Spigot or Purpur?

They are not at the same layer. Purpur is a Paper replacement, and Paper is itself downstream of Spigot, so choosing Purpur means choosing the Paper lineage plus Purpur's additional settings.

### How do I install plugins on a Purpur server?

Purpur is a drop-in replacement for Paper, so plugin installation follows the Paper layout: place plugin jars in the plugins directory generated on first run. The README does not document a Purpur-specific plugin installation step.

### How do I install mods on a Purpur server?

The repository describes Purpur as a server for the Bukkit and Paper plugin ecosystem, and it does not document mod loading. The README and repository layout give no mod installation steps.

## Sources

- [Issues](https://github.com/PurpurMC/Purpur/issues)
- [License: MIT](https://github.com/PurpurMC/Purpur/blob/ver/26.3/LICENSE)
- [Project website](https://purpurmc.org)
- [PurpurMC/Purpur on GitHub](https://github.com/PurpurMC/Purpur)
- [README](https://github.com/PurpurMC/Purpur/blob/ver/26.3/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/purpurmc-purpur