Instal & Upgrade

How to install or upgrade mcMMO on a Spigot, Paper, or Folia server, and what happens to your config and data.

mcMMO is a server-side plugin. Players don't install anything - only the server owner does. Installation is just "drop the jar in, restart."

Requirements

Requirement	Detail
Server software	Spigot, Paper, or Folia. Paper is recommended.
Minecraft version	1.20.5 or newer (this build targets API `1.20.5`).
Java	Java 17 or newer.

mcMMO officially supports Spigot, Paper, and Folia only. It needs the Spigot/Bukkit API - plain CraftBukkit will not work. Other forks may work but are unsupported.

These docs cover mcMMO 2.2.054. If you run an older Minecraft version, you'll need a matching older mcMMO build (see Legacy below).

Optional integrations

mcMMO will use these plugins if present, but none are required:

WorldGuard, CombatTag, HealthBar, PlaceholderAPI, ProtocolLib.

For example, WorldGuard lets you flag regions where mcMMO is disabled, and PlaceholderAPI exposes mcMMO stats to other plugins.

Installing mcMMO

Download the latest mcMMO from an official source:
- SpigotMC
- Voxel
Stop your server (or have it ready to restart).
Place mcMMO.jar into your server's plugins/ folder.
Start the server.

On first start, mcMMO creates its folder at plugins/mcMMO/ containing all the default config files, locale files, and (by default) your player data.

Upgrading mcMMO

Upgrading is intentionally painless - you are never required to delete your data or configs.

Download the latest mcMMO.jar.
Make sure your server software (Spigot/Paper/Folia) is up to date.
Stop the server.
Replace the old mcMMO.jar in plugins/ with the new one.
Start the server.

Your existing settings are preserved. When an update adds new settings, mcMMO will add them to your existing config files automatically - with a couple of exceptions, below.

Reloading is not supported. Always fully restart the server after installing, upgrading, or changing any config file. /reload can leave mcMMO in a broken state.

mcMMO respects your customizations and won't overwrite values you've changed. However, a few config files do not auto-add new entries - for these, new default keys simply won't exist until you add them:

treasures.yml
fishing_treasures.yml
repair.vanilla.yml
salvage.vanilla.yml

If you don't customize these files, the easiest path is to delete them and let mcMMO regenerate fresh defaults on the next restart. If you do customize them, follow the changelog each release and add new keys by hand.

Never delete the plugins/mcMMO/ folder itself - by default that's where player data is stored. Deleting it wipes everyone's progress. Deleting individual .yml config files is safe (they regenerate); deleting the folder is not.

There is also an upgrades_overhaul.yml in the folder - do not edit it. mcMMO uses it internally to track which one-time data upgrades it has already run.

See Configuration for what each file controls.

Legacy versions

If you run an older Minecraft version, you need the matching legacy mcMMO build:

Get the mcMMO version built for your Minecraft version.
Pair it with the latest Spigot/Paper for that same Minecraft version.
Drop the jar into plugins/ as usual.

Legacy builds are provided as-is and receive no fixes. If you hit problems, update to the latest Spigot (via BuildTools) or Paper for that version first. mcMMO's source is open, so technically-minded owners can fork and patch older versions themselves.

Coming from mcMMO Classic

You can upgrade straight from mcMMO Classic and your data will carry over. Note this is one-way: once the configs are upgraded, going back to Classic requires deleting the .yml files so Classic can regenerate its own.