Minecraft UUID Lookup: Every Way to Find a Player UUID

Look up a Minecraft UUID from a username — with a tool, Mojang's official API, in game, or from a server's own files. Plus what to do when it fails.

最近更新: 2026-07-23

A Minecraft UUID lookup is the act of turning something human — a username — into the 128-bit number the game actually uses, or turning that number back into a name. It sounds like one operation, but there are four genuinely different ways to do it, and they do not all give the same answer. This page covers all four, in order of how quickly they get you unstuck.

The short version: for a Java Edition account, the fastest path is the Locator Bar UUID finder — type the username, get the canonical UUID and, since you are here anyway, the exact color that UUID produces on the 1.21.6 Locator Bar.

Method 1: look it up on this site

Type a username into the finder. It resolves the name through Mojang's profile API, hyphenates the result into the canonical form, and hands back both the UUID and the derived Locator Bar color.

If you already have the UUID and only want to know what it looks like on the bar, paste the UUID instead — hyphenated or not, upper or lower case, both are accepted.

Three details worth knowing about any web lookup, including this one:

It only covers Java Edition. Mojang's lookup API is a Java Edition account service. Bedrock players are identified by Xbox User ID (XUID) instead, and there is nothing here to resolve.
Results are cached. A name-to-UUID mapping only changes when someone renames, which is rare, so caching hard is correct behaviour rather than staleness.
A miss is usually a real miss. Mojang answers an unknown name with an empty response, not with an error. If nothing comes back, the most likely explanation is a typo or a Bedrock-only name.

Method 2: Mojang's official API

Mojang runs a public, unauthenticated lookup service. These are the endpoints, taken from the Minecraft Wiki's Mojang API page.

Username to UUID

GET https://api.mojang.com/users/profiles/minecraft/<username>

Two equivalent modern endpoints exist and are worth knowing, because the legacy one on api.mojang.com is documented as occasionally returning spurious 403s due to a misconfiguration on Mojang's side:

GET https://api.minecraftservices.com/minecraft/profile/lookup/name/<username>
GET https://api.mojang.com/minecraft/profile/lookup/name/<username>

A successful response is small:

{
  "id": "069a79f444e94726a5befca90e38aaf5",
  "name": "Notch"
}

Note that id comes back without hyphens. Most commands and most tools want the hyphenated form, so you insert hyphens after characters 8, 12, 16 and 20:

069a79f4-44e9-4726-a5be-fca90e38aaf5

Two optional booleans, legacy and demo, may also appear — the first flags an account that never migrated to a Mojang/Microsoft account, the second a demo account.

UUID to username

GET https://api.minecraftservices.com/minecraft/profile/lookup/<uuid>

Same response shape. This returns the current name only.

Bulk lookup

POST https://api.mojang.com/profiles/minecraft

Also available as https://api.minecraftservices.com/minecraft/profile/lookup/bulk/byname. The body is a JSON array of up to 10 usernames, matched case-insensitively, and the response is an array of the same objects. Names that do not exist are simply absent from the array rather than returned as nulls, so match on the returned name field rather than on array position.

Skin and cape

GET https://sessionserver.mojang.com/session/minecraft/profile/<uuid>

Returns the profile with a properties array whose textures value is Base64-encoded JSON containing the skin and cape URLs. Add ?unsigned=false for a signed payload.

Rate limits

The Wiki documents a default per-IP limit of 200 requests per 2 minutes, with IPv6 addresses bucketed by /56 subnet. The session server is separately limited at roughly 400 requests per 10 seconds. Experimental rate limiting was introduced on 15 January 2025, so behaviour on the older endpoints can be inconsistent. Build in retries and cache aggressively.

The endpoint that no longer exists

https://api.mojang.com/user/profiles/<uuid>/names returned a player's full name history. Mojang removed it on 13 September 2022. There is no official replacement, and any site still claiming to show complete name history is either serving pre-2022 archived data or guessing.

CORS

Mojang's profile endpoints do not send CORS headers, so a browser cannot call them directly from another origin — the request is blocked before you ever see the response. That is why every web-based lookup, including ours, proxies the call through a server. If you are writing a browser extension or a front-end and getting a CORS error, this is why, and the fix is a small server-side proxy rather than any client-side flag.

Method 3: in game, with no website at all

If you are already in the world, the game will tell you.

Your own UUID:

/data get entity @s UUID

The reply is the int-array form — four signed 32-bit integers, most significant first:

[I;-132296786,2112623056,-1486552928,-920753162]

Converting that back to hyphenated hex means reading each integer as an unsigned 32-bit value, writing it as 8 hex digits, concatenating all four, and inserting hyphens. Tedious by hand, trivial in any calculator, and the source of most "why does this look nothing like a UUID" confusion.

Another player's UUID: the same command with their name in place of @s, which needs permission level 2.

Any entity's UUID: point at it and use a selector, for example /data get entity @e[type=creeper,limit=1,sort=nearest] UUID. Every entity has one — mobs, armour stands, dropped items, arrows. Mob UUIDs are generated fresh at spawn, which is exactly why a mob's Locator Bar color looks arbitrary while a player's stays put.

Method 4: straight off the server

A server that a player has joined already knows their UUID, and stores it in plain JSON in the server directory.

whitelist.json — whitelisted players. The Wiki is explicit that whitelisting "works by checking UUID or XUID of the players who have been whitelisted on a server," so each entry pairs a UUID with the name it had when it was added.
banned-players.json — "specifies players that are banned from the server," again keyed on UUID so a rename cannot dodge a ban.
ops.json — "specifies operator status of players," with the permission level.
usercache.json — the server's own name-to-UUID cache, written as players join.
world/playerdata/ — one .dat file per player, named after the player's UUID. A directory listing here is itself a UUID lookup.

This is the only method that works with the server offline, and the only one that works for offline-mode players.

Offline-mode lookups need a different approach entirely

If the server runs with online-mode=false, its players have no Mojang accounts and no Mojang UUIDs. Asking the API about them is meaningless — either you get nothing back, or worse, you get the UUID of the real account that happens to own that name, which is not the identity the server is using.

Offline UUIDs are computed, not looked up. Per the Minecraft Wiki, an offline player's identifier is "UUID version 3, generated from the MD5 hash of OfflinePlayer:<username>." Concretely: take the UTF-8 bytes of the string OfflinePlayer: followed by the exact username, MD5 them, then set the version nibble to 3 and the variant bits to the RFC layout — which is precisely what Java's UUID.nameUUIDFromBytes() does, documented by Oracle as returning "a type 3 (name based) UUID."

Worked example: OfflinePlayer:Notch yields b50ad385-829d-3141-a216-7e7d7539ba7f. The 3141 in the third group is the fingerprint — version 3. Compare with the real account's 069a79f4-44e9-4726-a5be-fca90e38aaf5, version 4. Same player name, two unrelated identities.

The practical rule: if a UUID's third group starts with 3, stop looking it up online. It was computed from a name on somebody's offline server, and no API knows about it. More on the online/offline split in what a Minecraft UUID is.

When a lookup fails

Empty response or 404. No Java Edition account by that name. Check spelling and underscores; usernames are 3–16 characters of letters, digits and underscores only. If the player is on Bedrock, there is no UUID to find.

403 Forbidden. Documented behaviour of the legacy api.mojang.com/users/profiles/minecraft/ endpoint, which "will occasionally return random 403 errors due to a misconfiguration." Retry, or switch to the api.minecraftservices.com endpoint.

429 Too Many Requests. You crossed the rate limit. Wait, then batch through the bulk endpoint instead of firing one request per name.

CORS error in a browser console. Expected — see above. Proxy the request server-side.

The UUID resolves but to the wrong player. Almost always an offline-mode server, or a name that has been released and re-registered by somebody else. Names are recyclable; UUIDs are not.

Once you have the UUID

A UUID on its own is not very interesting. What it unlocks is:

The Locator Bar color. Java Edition derives a player's default waypoint color from their UUID. Paste the UUID into the finder to see it, or read the full derivation if you want to reproduce the maths yourself.
Color clashes in a party. Two teammates can land on near-identical colors by pure chance. Run the group through the color checker before the raid rather than during it.
A fixed color. If the default is bad, override it — the waypoint command generator writes the /waypoint line, and Locator Bar colors covers the 16 named colors and custom hex.