Minecraft Offline UUID Generator

Exactly how Minecraft computes offline UUIDs

The entire mechanism lives inside Java's standard library in one line that every Bukkit-based server has called since 2012. Here it is as it appears in CraftBukkit's PlayerProfile code:

UUID offlineUUID = UUID.nameUUIDFromBytes(
    ("OfflinePlayer:" + username)
        .getBytes(StandardCharsets.UTF_8)
);

UUID.nameUUIDFromBytes is defined in RFC 4122 §4.3 as a version-3 UUID: compute the MD5 digest of the input bytes, then overwrite two nibbles to encode the version and variant. Concretely:

• byte[6]Upper nibble forced to 0x3_ — encodes UUID version 3.
• byte[8]Top two bits set to 10 — encodes the RFC 4122 variant.

The resulting 16 bytes are printed in lowercase hex, split by hyphens into the familiar 8-4-4-4-12 pattern. That's the UUID your server writes to ops.json, whitelist.json, world/playerdata/, and every plugin's per-player storage.

Why the "OfflinePlayer:" prefix?

Without a namespace, a player named abc could theoretically hash to a UUID that Mojang happened to assign to a completely different account. By prepending OfflinePlayer:, all offline UUIDs are generated from a hash space Mojang never touches. Collision between an offline UUID and a real Mojang UUID is effectively impossible.

Online UUID vs. Offline UUID — what's the difference?

When you actually need an offline UUID

Most server admins only stumble across offline UUIDs when something breaks. Here are the real situations where knowing the exact UUID before the player connects matters:

Granting operator status before first join

ops.json stores entries like {"uuid":"...","name":"Steve","level":4}. If you put in the wrong UUID the server will create a second, duplicate entry the moment that player actually joins, and the first entry will never match. Generate the correct offline UUID here, paste it into ops.json, and you're done.

Whitelist setup without a live server

You're configuring a new server, or the server is offline for maintenance, and you want to pre-populate whitelist.json. Same deal as ops — the UUID must match what the server would compute. Enter each username here and paste the results in.

Plugin data migration and repair

Bukkit plugins typically store per-player files named <UUID>.yml or rows keyed by UUID in a database. Common culprits include EssentialsX (user data, homes, economy), LuckPerms (permissions), Vault-backed economy plugins, land-claim plugins like GriefPrevention and Lands, and virtually every RPG or progression plugin. If you're moving player data between servers, fixing corrupted records, or importing from a backup taken under a different UUID, you need the exact offline UUID.

Online-mode → offline-mode migration

This is the most painful scenario. Switching online-mode from true to false means every player gets a new UUID on their next login. Old world data, plugin files, and database rows all sit under the Mojang UUID. The workflow is: fetch each player's Mojang UUID from the API, generate their offline UUID with this tool, then rename every file and update every database row accordingly. Skip this step and players lose all their progress.

Writing plugins and admin scripts

If your plugin needs to look up a player who has never joined (e.g. to pre-grant permissions, create a starting kit, or seed an economy balance), you can't call Bukkit.getOfflinePlayer(name) without potentially blocking the main thread. Compute the UUID yourself with the same formula, use the Java or Python output from this tool, and construct the UUID directly.

BungeeCord and Velocity networks

In a proxy network the UUID situation gets layered. If the proxy runs in offline mode, it computes the offline UUID and forwards it to all backends — the backend's own online-mode setting becomes irrelevant for UUID assignment. If the proxy is in online mode, it fetches the Mojang UUID and passes that through, regardless of backend config. Know which mode your proxy uses before relying on this tool for a network.

Common mistakes and gotchas