Paper: installing and configuring your server

In short: download the jar from papermc.io/downloads/paper, install the right Java (21 for Paper 1.20–1.21.11, 25 for 26.1 and newer), run java -Xms4G -Xmx4G -jar paper.jar --nogui, accept the EULA in eula.txt and start it again. Paper's settings live in config/, plugins go in plugins/.

What Paper is#

Paper is a Minecraft: Java Edition server by the PaperMC team. It started as a Spigot fork, and since 1.21.4 it has evolved independently and no longer pulls in Spigot's changes. bukkit.yml and spigot.yml are still there and work as before.

Paper runs Bukkit, Spigot and Paper plugins, fixes vanilla mechanics bugs and adds a lot of settings. Forks such as Leaf and Purpur are built on it, so everything below applies there too. For a comparison with other options, see which server software to choose.

Which Java you need#

Don't set -Xmx right at your plan's limit: Java and the operating system need headroom on top, and Paper's docs suggest leaving about 1–1.5 GB. How much memory your player count needs is covered in how much RAM a server needs.

Installing Paper step by step#

1. 1

   Download it

   On the downloads page, pick your Minecraft version and click the build number. Older builds are in the build explorer, linked from the same page. Only download Paper from the official site.

2. 2

   Prepare a folder

   Create an empty server folder and put the jar in it. Renaming it to paper.jar saves you editing the start script on every update.

3. 3

   Start the server

   Open a terminal in that folder and run the command below. -Xms and -Xmx set the memory, --nogui turns off the vanilla GUI window. A ready start script with recommended JVM flags comes from PaperMC's script generator.

4. 4

   Accept the EULA

   On first start the server creates eula.txt and stops. Read the Minecraft EULA, set eula=true and start the server again.

5. 5

   Check it

   Join and run /version — it shows the Paper version and build. /plugins lists plugins: green ones are running, red ones failed to load.

java -Xms4G -Xmx4G -jar paper.jar --nogui

Coming from Vanilla? Just swap the jar: Paper converts the world to its layout by itself. From Spigot on versions before 26.1, Paper is a drop-in replacement; from 26.1 on, a direct move isn't possible — first convert the world to the Vanilla layout following Spigot's instructions.

What's where#

Where paper-world.yml lives depends on the version. On 1.21.x each dimension has its own folder in the server root: world/, world_nether/, world_the_end/. Since 26.1 Paper stores worlds closer to Vanilla: dimensions sit in world/dimensions/minecraft/ (overworld, the_nether, the_end), with a paper-world.yml in each.

How per-world settings work#

Defaults live in config/paper-world-defaults.yml and apply to every world. To change something for one world, add only that line to its paper-world.yml. Don't copy the whole file: anything missing from paper-world.yml is inherited from the defaults.

entities:
  spawning:
    spawn-limits:
      monster: 90

This example from Paper's docs raises the monster limit in the Nether only (the path is for 26.x; on 1.21.x the file is in world_nether/). Every other world keeps the defaults.

Settings worth knowing#

Out of the box Paper is configured sensibly. Below are the settings people ask about most; defaults are from Paper's docs. Change one at a time and check the result.

Profiling: spark is built in#

Since 1.21 Paper bundles the spark profiler. Run it while the lag is happening: after 10 minutes spark returns a link to the report. The old Timings profiler has been off by default since 1.21 and can't be enabled at all since 1.21.3.

/spark profiler start --timeout 600

What usually turns out to be the cause and how to read the report is in why your server lags.

Updating Paper#

New builds bring fixes, so PaperMC recommends updating at least once a week. The order:

1. 1

   Back up

   Worlds, server configs, plugins and their configs. It's the most important step and the one people skip most.

2. 2

   Plugins via the update folder

   Create plugins/update and put the new plugin versions there. On the next restart Paper swaps them in itself — no touching jars on a running server.

3. 3

   The new Paper build

   Download it, stop the server, replace the old jar with the new one under the same name and start.

4. 4

   The log

   Watch the startup log: plugin conflicts show up right away.

An anticheat on Paper#

Paper is one of the two platforms DGuard is built for (the other is Leaf). Supported versions are Paper 1.21–26.3. The main version is 1.21.11: DGuard is tested on it and runs on it on production servers; the others are supported but haven't been run on production servers yet.

Setup works like any plugin: add the server in the panel to get a key, put the latest PacketEvents release and DGuard.jar into plugins/, paste the key into plugins/DGuard/config.yml → license.key and restart. Checks run in network threads rather than the main thread, so TPS stays at 20: on a live server DGuard takes 0.03% of one core on the main thread.

FAQ#