How to Set Up and Manage a Minecraft Whitelist

A whitelist is the simplest way to lock down your Minecraft server. Only players on the list can connect; everyone else sees a message telling them they are not allowed. For a friends-only server or a private community, it is the first setting you should enable.

Without a whitelist, anyone who knows the IP address can join. That is fine for public servers, but for a small group it invites griefers, bots and random players who clutter up chat. A whitelist gives you complete control over who gets in, without needing a permissions plugin or extra configuration.

Enabling the whitelist

There are two ways to turn on the whitelist:

• In server.properties: set white-list=true and restart the server. This is the permanent option.
• In the console: type whitelist on. This takes effect immediately without a restart. The setting persists across reboots once you use it.

On Paper and Purpur servers (which includes all HostValues Minecraft plans), both methods work identically. The console command is faster when you want to enable the whitelist on a running server without kicking everyone off during a restart.

Adding and removing players

Use the following commands in the console or in-game as an operator:

• whitelist add PlayerName adds a player to the list.
• whitelist remove PlayerName removes a player from the list.
• whitelist list shows all whitelisted players.

The player does not need to be online to be added. Minecraft resolves the name to a UUID behind the scenes, so even if the player has never joined your server before, the command works.

Editing whitelist.json directly

The whitelist is stored in a file called whitelist.json in the root directory of your server. Each entry contains the UUID and name of a player:

[
  {
    "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "name": "PlayerName"
  }
]

You can edit this file through the Files tab in the game panel. To add a player manually, insert a new block with their UUID. You can look up UUIDs at mcuuid.net. After editing the file, type whitelist reload in the console to apply the changes without restarting.

This method is useful when you need to add many players at once. Copy the JSON structure, fill in the UUIDs and paste them in. Much faster than running the command twenty times.

The enforce-whitelist setting

In server.properties there is a second setting: enforce-whitelist. When set to true, any player who is removed from the whitelist while online gets kicked immediately. Without this setting, removed players stay connected until they leave on their own.

For most servers, enabling enforce-whitelist makes sense. If you remove someone from the list, you probably want them gone right away.

Whitelist vs ban

A whitelist is an access list: only players on it can join. A ban is an exclusion list: everyone can join except banned players. The two serve different purposes:

• Whitelist: best for private servers where you know every player. Nobody unexpected gets in.
• Ban: best for public servers where you want everyone to be able to join, but need to remove specific troublemakers.

You can use both at the same time. A whitelisted server with a ban list means a player must be on the whitelist and not on the ban list to connect.

Whitelist with Bedrock players (Geyser and Floodgate)

If you use Floodgate to let Bedrock players join your Java server, those players can be whitelisted too. Floodgate prefixes Bedrock names with a character (a dot by default):

whitelist add .BedrockPlayerName

Without Floodgate, Bedrock players need a linked Java account to appear on the whitelist. If you use Geyser without Floodgate, the Bedrock player must have a Java account that you whitelist under their Java name.

Whitelist on a network with Velocity

On a Velocity proxy network, the whitelist should be configured on the proxy, not on the backend servers. Velocity has its own whitelist commands. If you whitelist on the backends instead, players can still connect to the proxy and see error messages when they try to switch servers, which is a confusing experience.

Can I combine a whitelist with plugins like GriefPrevention?

Yes. The whitelist controls who enters your server. GriefPrevention controls what they can do once inside. The two complement each other perfectly. A whitelist is the front door; claim protection is the lock on each room. For a private SMP, using both gives you the best balance of access control and in-game protection.

Does the whitelist reset when I update my server?

No. The file whitelist.json is never overwritten by a version update or jar switch. Your list stays intact across updates, restarts and even server migrations.

Can I whitelist by IP address instead of username?

Vanilla Minecraft does not support IP-based whitelisting. If you need IP restrictions, you would use a firewall rule on a VPS, or a plugin that adds IP verification. For most servers, name-based whitelisting is sufficient and much easier to manage.

Setting up a whitelist takes two minutes. Try it on your HostValues Minecraft server.