MCUtility

How to create a Minecraft server whitelist

Turn the whitelist on with /whitelist on and add each player with /whitelist add <name>. For a long list, build a whitelist.json in the Whitelist Creator, save it in the server folder and run /whitelist reload.

Java Edition · Checked against Java Edition 26.3 · Published

New in Java Edition 26.3

New servers now start with white-list=true, so only operators can join until players are added. Servers created before 26.3 keep the value already in their server.properties.

Option 1: commands

Run these as an operator in game, or in the server console without the slash:

CommandWhat it does
/whitelist onTurns the whitelist on and saves white-list=true.
/whitelist add <player>Adds a player. They don’t need to be online.
/whitelist remove <player>Removes a player.
/whitelist listShows everyone on the list.
/whitelist reloadReads whitelist.json from disk again after you edit it.
/whitelist offTurns the whitelist off.

Option 2: a whitelist.json file

For a group of friends or a list from an application form, a file is faster than typing commands. The file is a list of players with their UUID and name:

[
  {
    "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
    "name": "Notch"
  }
]
  1. Paste the usernames into the Whitelist Creator. It looks up each UUID, skips duplicates and flags names that don’t exist.
  2. Download whitelist.json and save it next to server.properties, replacing the old file.
  3. Run /whitelist reload, or restart the server.

If the server is running, reload before using /whitelist add or remove again. The server saves its own copy of the list when it changes, which would overwrite edits it hasn’t loaded.

The two settings in server.properties

  • white-list turns the whitelist on or off. /whitelist on and off change it for you.
  • enforce-whitelist kicks players who are online but not on the list when the whitelist is reloaded. Without it, a removed player stays online until they leave.

The server.properties Generator has both under Network and security.

Things that catch people out

  • Operators always get in. In Java Edition, players in ops.json can join even when they aren’t whitelisted.
  • Offline mode uses different UUIDs. With online-mode=false, players are identified by an offline UUID calculated from their name, so account UUIDs from a lookup won’t match.
  • Name changes are fine. Entries are matched by UUID, so a renamed player stays whitelisted.
  • Bedrock is different. Bedrock Dedicated Server uses allowlist.json, the /allowlist command and Xbox accounts, and operators there must be on the list too.