Minecraft Server Whitelist: How to Set It Up

A whitelist makes your server private: only the players you add can join, and everyone else is turned away at the door. It is the simplest way to run a server for friends. Java Edition calls it the whitelist; Bedrock Dedicated Server calls it the allowlist.

How to turn on the whitelist

1. Add yourself first

   In the server console, run whitelist add <your name>. On Java, operators can always join, but adding yourself avoids surprises if you are ever de-opped.

2. Add your friends

   Run whitelist add <name> for each player. Use their current Minecraft username. They do not need to be online.

3. Switch it on

   Run whitelist on. You can also set white-list=true in server.properties and restart the server.

4. Decide about players already online

   Anyone already connected stays online until they leave. With enforce-whitelist=true (below), players who are not on the list are kicked whenever the whitelist is reloaded.

Whitelist commands

In the game, type the same commands with a slash, such as /whitelist add Steve. They only work on a dedicated server, not in a singleplayer or LAN world. For the rest of the admin commands, see our Minecraft server commands list.

The whitelist.json file

The server keeps the whitelist in whitelist.json, next to server.properties. Each player has their account UUID and name:

[
  {
    "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
    "name": "Notch"
  }
]

• The UUID is what counts. Players are matched by UUID, so someone who changes their username stays whitelisted.
• Prefer the command. whitelist add looks up the UUID for you. If you edit the file by hand, get each UUID from the Minecraft UUID lookup, then stop the server first or run whitelist reload as soon as you save.
• Offline-mode servers match players by an offline UUID made from their username, not their real account UUID (the UUID lookup shows both). Keep online-mode=true if you want the whitelist to protect you.

Whitelist vs enforce-whitelist

Both are settings in server.properties, and they do different jobs:

• `white-list=true` decides who can connect. Anyone not on the list is refused when they try to join.
• `enforce-whitelist=true` decides what happens to players already online. When the whitelist is reloaded, anyone connected who is not on it is kicked. It is off by default, so removed players stay until they leave.

Turn both on if you ever need to remove someone mid-session. Changes to server.properties need a server restart.

Bedrock allowlist (Bedrock Dedicated Server)

Bedrock renamed the whitelist to the allowlist in version 1.18.10. It works the same way, with a few differences:

• Turn it on in server.properties with allow-list=true, then restart. There is no allowlist on or off command.
• Use gamertags: allowlist add <gamertag>, allowlist remove <gamertag>, allowlist list and allowlist reload. Put gamertags with spaces in quotes, like allowlist add "Blue Fox 42".
• Operators are not exempt. On Bedrock, every player, including operators, must be on the allowlist.
• The file is `allowlist.json`. Entries use the gamertag in name. The Xbox account ID, xuid, is optional when name is set, and ignoresPlayerLimit lets a player join a full server.

[
  {
    "ignoresPlayerLimit": false,
    "name": "Blue Fox 42"
  }
]

Realms does not use a whitelist. Only players the owner invites can join a Realm.

Minecraft whitelist not working?

• A friend is whitelisted but still refused. Check the spelling with whitelist list. If they changed their name after you added them, they are still on the list under their UUID.
• `whitelist add` says the player does not exist. The name may be wrong, or Mojang's profile lookup may be down. Check whether Minecraft is down; if skins and profiles show a problem, try again later.
• Your edits to whitelist.json disappeared. The server rewrites the file when a command changes the list. Edit it while the server is stopped, or reload straight after saving.
• Removed players are still online. That is expected unless enforce-whitelist=true is set.
• Bedrock operators cannot join. Add them to the allowlist too.

Running the server from home? Friends outside your network also need port forwarding before the whitelist even comes into play.