How do I create a Minecraft whitelist from player names?

Enter each Java Edition username on its own line, choose Online mode (for online-mode=true servers) or Offline mode (for online-mode=false), click Generate Whitelist, then copy or download the JSON. Place the file as whitelist.json in your server root folder and set white-list=true in server.properties.

What is the difference between online and offline whitelist UUIDs?

Online mode looks up each username on Mojang's API and uses the account's permanent Mojang UUID — required when server.properties has online-mode=true. Offline mode generates a version-3 UUID from MD5("OfflinePlayer:" + username), which is what Bukkit/Paper/Spigot assign when online-mode=false. Using the wrong UUID type means whitelisted players cannot join.

Where does whitelist.json go on a Minecraft server?

whitelist.json lives in the root folder of your server — the same directory as server.properties, eula.txt, and the world folder. Stop the server before replacing the file, or run /whitelist reload after updating it while the server is running.

How do I enable the whitelist on my Minecraft server?

In server.properties set white-list=true and enforce-whitelist=true. Restart the server or run /whitelist reload. Only players listed in whitelist.json can connect. Operators can still join unless enforce-whitelist is true and they are not on the list — add ops to the whitelist too if needed.

Can I add players to an existing whitelist without losing entries?

Yes. Enable "Merge with existing whitelist" on this tool, paste your current whitelist.json contents, generate new entries, and the output combines both lists without duplicate UUIDs. Alternatively use /whitelist add in-game for one player at a time.

Why does a player name fail in online mode?

Common causes: typo in the username, wrong capitalisation (Mojang returns the current official name), account does not exist, or the name belongs to Bedrock-only (Bedrock gamertags are not always valid Java usernames). Java usernames must be 3–16 characters using letters, digits, and underscores only.

Does this work for Bedrock Edition servers?

This tool generates Java Edition whitelist.json format (uuid + name). Bedrock Dedicated Server uses allowlist.json with a different structure based on XUID identifiers, not Mojang Java UUIDs. For Bedrock, use the BDS allowlist commands or panel tools instead.

What format does whitelist.json use in modern Minecraft?

Since Minecraft 1.7.6, whitelist.json is a JSON array of objects: [{"uuid":"869ed7c6-336c-4493-ab73-8954d47cc442","name":"Notch"}]. Each entry requires both uuid and name fields. The server matches connecting players by UUID, not by name alone.

How many players can I add at once?

This tool accepts up to 50 usernames per generation. For larger lists, run multiple batches and merge using the existing-whitelist option, or use a script with Mojang's batch API. In-game /whitelist add works for adding players one at a time without editing the file.

Is offline whitelist generation safe — does it send data anywhere?

In offline mode, UUIDs are computed entirely in your browser using the same MD5 algorithm as the server. No usernames leave your device. Online mode sends usernames to our server, which queries Mojang's public profile API to retrieve official UUIDs.

Tools · Server admin

Minecraft Whitelist Creator

Enter one or more player names below (one per line) to generate their UUIDs. Select Online or Offline server mode, click Generate Whitelist, and get a ready-to-use whitelist.json — or export /whitelist add commands, CSV, and a name-only list.

Up to 50 names · merge existing whitelist · download JSONOnline (Mojang UUID) · Offline (instant browser hash)

Server mode

Player names0 / 50 names

One username per line. Duplicates are removed automatically. Java Edition usernames: 3–16 characters, letters, digits, underscore.

Merge with existing whitelist

Online vs offline whitelist — pick the right mode

The UUID in each whitelist entry must match what your server assigns when that player connects. Pick the wrong mode and whitelisted players get "You are not whitelisted on this server" even though their name is in the file.

Setting	Online mode tool	Offline mode tool
server.properties	`online-mode=true`	`online-mode=false`
UUID source	Mojang / Microsoft account	MD5 hash of username
Account required	Yes — paid Java account	No — any username string
Lookup method	Mojang API (via this tool)	Instant in browser
Changes on rename?	UUID stays same; update name field	New name = new UUID entirely

Still unsure which UUID a player has? Use the Offline UUID Generator to compare, or check the server log line UUID of player X is Y when they join.

Installing and enabling whitelist.json

Generate the file — use this tool, download whitelist.json, or copy the JSON output.
Stop the server — safest before replacing the file. Alternatively edit live and run /whitelist reload.
Place the file — server root, same folder as server.properties.
Enable in server.properties:
```
white-list=true
enforce-whitelist=true
```
Restart or reload — /whitelist reload applies file changes without full restart on Paper/Spigot.

Add yourself and all operators to the whitelist before enabling enforce-whitelist=true — otherwise you can lock yourself out. Keep console/RCON access as a backup.

In-game commands vs editing whitelist.json

/whitelist add <player>

Best for one player at a time while the server runs. Paper resolves the correct UUID automatically — no manual lookup needed. Export the "/whitelist add" format from this tool if you prefer pasting commands into console.

Edit whitelist.json directly

Best for bulk adds before first launch, migrations, or when the server is offline. This tool generates the exact JSON structure the server expects — no hand-typed UUIDs.

Plugin-managed whitelists

Plugins like LuckPerms, CMI, or dedicated whitelist plugins may sync with whitelist.json or maintain a separate database. Check your plugin docs before overwriting the file.

Proxy networks (Velocity / BungeeCord)

Whitelist is usually enforced on the backend server players actually join, not the proxy — unless you use a proxy-level whitelist plugin. Generate UUIDs matching each backend's online-mode setting.

Frequently asked questions

What does whitelist.json look like?

[
  {
    "uuid": "869ed7c6-336c-4493-ab73-8954d47cc442",
    "name": "Notch"
  },
  {
    "uuid": "61699b2e-d327-4a01-9f1e-4960ca466109",
    "name": "jeb_"
  }
]

Player renamed their account — do I update the whitelist?

On online-mode servers the UUID stays the same but the name field should match their current username. Re-generate with the new name or run /whitelist add NewName — the server updates the entry. On offline servers a rename means a completely new UUID.

Can I whitelist Bedrock players on a Java server?

Only if they connect through a crossplay proxy (Geyser/Floodgate) that maps Bedrock identities to Java UUIDs. Standard Java whitelist.json uses Java account UUIDs. Floodgate assigns its own UUID prefix for Bedrock players — use Floodgate's whitelist commands for those users.

Where can I find servers that use whitelists?

Many private SMP and application-based servers use whitelists. Browse the Minecraft server list to discover communities — check each server's listing for whitelist or application requirements.