Compatibility
Minecraft: Java Edition
Platforms
Tags
Creators
Details
Switch your server between online mode and offline mode without anyone losing their stuff.
Minecraft saves player data by UUID, and a player's UUID depends on the server's mode. Switch online-mode and everyone gets a new UUID. Their old inventory is still on disk, but the server doesn't look there, so they spawn with nothing.
UserOverUUID moves the data to the new UUID when the player joins, before the server loads it. They spawn with their inventory, ender chest, XP, position, stats and advancements, no rejoin needed.
Features
- Automatic. Migrates on join, before the server reads the player's data.
- Both directions. Online to offline, offline to online, and back again later.
- Safe defaults. Copies instead of moving, never replaces existing data on its own, and backs up every file it touches.
- Runs once per player. A ledger remembers finished migrations, so nothing repeats on the next login.
- Proxy aware. Works behind BungeeCord and Velocity.
- No internet needed. Online UUIDs are found in
usercache.jsonand in the names saved inside player data. The Mojang API is an optional last resort. - Plugin data. Add any plugin file or folder that is named after a UUID, such as Essentials userdata.
- 1.19 to 26.x. Supports the
players/folder layout that Minecraft 26.1 introduced.
Getting started
- Put the jar in
plugins/and restart. - Change
online-modeinserver.properties(or your proxy's setting) and restart. - Done. Each player gets their data back the first time they join.
Switched before installing the plugin? Anyone who joined in between now has a fresh, empty profile under their new UUID, and the plugin won't overwrite that on its own. Check with /uom status <player> and bring the old data back with /uom migrate <player> --force. The fresh profile is backed up first.
Commands
Every command needs useroveruuid.admin (op by default). /uom and /uuidmigrate are aliases.
| Command | What it does |
|---|---|
/uom status <player> |
Shows both UUIDs, where they were found, and whether there is anything to migrate |
/uom dryrun <player> |
Lists every file a migration would copy, without changing anything |
/uom migrate <player> |
Migrates now. Kicks the player first if they are online |
/uom reload |
Reloads config.yml |
dryrun and migrate take these options:
--forcereplaces data that already exists under the new UUID (backed up first)--to-onlineor--to-offlinepicks the direction yourself, for example to prepare before switching
How it decides
| Player joins with | Data is copied from |
|---|---|
| An offline UUID | Their online UUID, looked up in usercache.json, then in saved player data, then the Mojang API (if enabled) |
| An online UUID | Their offline UUID. Other spellings of the name (steve vs Steve) are checked too |
| A Bedrock (Floodgate) UUID | Nothing, Bedrock players are skipped |
If the player already has data under the new UUID, it is kept and the console tells you how to replace it. The one exception is switching back: when the existing file is the stale copy left behind by the last migration and the other side is newer, it gets replaced (and backed up), so going online, offline and online again loses nothing.
Configuration
config.yml
# Migrate a player's data automatically the first time they join with their other UUID.
autoMigrate: true
# COPY keeps the files under the old UUID (safest). MOVE deletes them after migrating.
operation: COPY
# Replace data a player already has under their new UUID? Leave false and use
# /uom migrate <player> --force for single players instead.
overwriteTarget: false
# Kick the player after an automatic migration. Normally not needed.
kickAfterMigrate: false
kickMessage: "&aYour player data was migrated. Please rejoin."
worlds:
autoDetect: true
additionalWorldFolders: []
lookup:
useUsercache: true
scanPlayerData: true
useMojangApi: false
mojangApiTimeoutMs: 3000
cacheTtlMinutes: 1440
paths:
includeVanillaPlayerdata: true
includeStats: true
includeAdvancements: true
# Placeholders: {uuid}, {uuid_nodash}, {name}. Relative to the server folder.
customPaths:
- "plugins/Essentials/userdata/{uuid}.yml"
Backups
Every migration writes a backup to plugins/UserOverUUID/backups/<date>_<player>_<uuid>/. It holds the migrated files, any files they replaced, and a manifest.txt listing what went where. To undo a migration, copy the files back while the player is offline.
Good to know
- For plugin data, only the file name or folder changes. Plugins that store UUIDs inside their files or in a database (LuckPerms, MySQL economies) need their own migration tools.
- In offline mode anyone can join under any name, so whoever joins as "Steve" gets Steve's migrated data. Use an authentication plugin if that matters on your server.
- Runs on Paper, Purpur, Spigot and Bukkit. Folia is not supported.
Upgrading from 1.0.0
Version 1.0.0 was called UuidMigrate. Delete UuidMigrate-1.0.0.jar and add the new jar. Your config and backups are copied over from plugins/UuidMigrate automatically, and /uuidmigrate and uuidmigrate.admin keep working.
Support
Found a bug, or want support for another plugin's data? Open an issue or ask on Discord.


