Paper

A PaperMC server can be automatically downloaded, upgraded, and run by setting the environment variable TYPE to "PAPER".

By default, the container will find and download the latest build for the VERSION chosen. If VERSION is not specified, then the latest Minecraft version released by PaperMC is selected. Along with a specific VERSION, a specific Paper build can be selected by setting the environment variable PAPER_BUILD.

To allow for the selection of experimental builds, set PAPER_CHANNEL to "experimental", otherwise only release/default channel builds are selected.

Example

Using docker run command line

docker run ... -e TYPE=PAPER ... 

docker run ... -e TYPE=PAPER -e VERSION=1.20.6 ... 

docker run ... -e TYPE=PAPER -e VERSION=1.20.6 -e PAPER_BUILD=140 ... 

docker run ... -e TYPE=PAPER -e PAPER_CHANNEL=experimental ...

Using a compose file:

environment:
  TYPE: PAPER

environment:
  TYPE: PAPER
  VERSION: 1.20.6
  PAPER_BUILD: 140

environment:
  TYPE: PAPER
  PAPER_CHANNEL: experimental

Tip

If you see the following error, it likely means you need to set the env var PAPER_CHANNEL to "experimental"

No build found for version 1.21 with channel 'default'

If you are hosting your own copy of Paper you can override the download URL with PAPER_DOWNLOAD_URL=<url>.

If you have attached a host directory to the /data volume, then you can install plugins via the plugins subdirectory. You can also attach a /plugins volume. If you add plugins while the container is running, you'll need to restart it to pick those up.

You can also auto-download plugins using SPIGET_RESOURCES.

Alternatives¶

Pufferfish¶

A Pufferfish server, which is "a highly optimized Paper fork designed for large servers requiring both maximum performance, stability, and "enterprise" features."

-e TYPE=PUFFERFISH

Note

The VERSION variable is used to select branch latest, 1.18, or 1.17. Use PUFFERFISH_BUILD to really select the SERVER VERSION number.

Extra variables:

PUFFERFISH_BUILD=lastSuccessfulBuild : set a specific Pufferfish build to use. Example: selecting build 47 => 1.18.1, or build 50 => 1.18.2 etc
FORCE_REDOWNLOAD=false : set to true to force the located server jar to be re-downloaded
USE_FLARE_FLAGS=false : set to true to add appropriate flags for the built-in Flare profiler

Purpur¶

A Purpur server, which is "a drop-in replacement for Paper servers designed for configurability and new, fun, exciting gameplay features."

-e TYPE=PURPUR

Note

The VERSION variable is used to lookup a build of Purpur to download

Extra variables:

PURPUR_BUILD=LATEST : set a specific Purpur build to use
FORCE_REDOWNLOAD=false : set to true to force the located server jar to be re-downloaded
USE_FLARE_FLAGS=false : set to true to add appropriate flags for the built-in Flare profiler
PURPUR_DOWNLOAD_URL=<url> : set URL to download Purpur from custom URL.

Leaf¶

A Leaf server is a Paper fork focused on performance improvements and low-level optimizations for smoother gameplay.

To use a Leaf server, set the environment variable TYPE to "LEAF".

-e TYPE=LEAF

Note

The VERSION variable is used to select the Minecraft version to run.
To specify a particular Leaf build, use LEAF_BUILD.

By default the latest build will be used; however, a specific build number can be selected by setting LEAF_BUILD, such as

-e VERSION=1.21.4 -e LEAF_BUILD=441

Folia¶

A Folia server can be used by setting the environment variable TYPE to "FOLIA".

By default, the container will run the latest experimental build of Folia server, but you can also choose to run a specific build with -e FOLIABUILD=26. The release channel can be changed with the variable FOLIA_CHANNEL; however, only experimental builds are available at this time.

Example

Using docker run

docker run -d --pull=always \
    -v /path/on/host:/data -e TYPE=FOLIA \
    -p 25565:25565 -e EULA=TRUE --name mc itzg/minecraft-server

If you are hosting your own copy of Folia you can override the download URL with FOLIA_DOWNLOAD_URL=<url>.

If you have attached a host directory to the /data volume, then you can install plugins via the plugins subdirectory. You can also attach a /plugins volume. If you add plugins while the container is running, you'll need to restart it to pick those up.

You can also auto-download plugins using SPIGET_RESOURCES.

Note

The Folia type inherits from the Paper type. Paper's variables will override the Folia ones.

Extra config¶

SKIP_DOWNLOAD_DEFAULTS: when set to "true" startup will entirely skip checking for default Paper/Bukkit/Spigot config files to download

Configuration Repositories¶

You can automatically download optimized or custom configuration files (e.g., bukkit.yml, spigot.yml, paper-global.yml, purpur.yml) by setting a repository URL. The container will automatically append the Minecraft version to the URL (e.g., <REPO_URL>/1.21.1/<FILE>).

Server Type	Variable
Paper	`PAPER_CONFIG_REPO`
Pufferfish	`PUFFERFISH_CONFIG_REPO`
Purpur	`PURPUR_CONFIG_REPO`

Server Properties¶

You can also download a base server.properties file using SERVER_PROPERTIES_REPO_URL.

Smart Mode: If the URL does not end in .properties, the script treats it as a base URL and appends /${VERSION}/server.properties (matching the behavior of the config repos).
Direct Mode: If the URL ends in .properties, it downloads that specific file.

Note: Environment variables (like MOTD, DIFFICULTY, MAX_PLAYERS) defined in your Docker configuration will override values in the downloaded server.properties file.