1. Introduction

Short version: you want to allow only selected players to join your Minecraft server.
This is done using the built-in whitelist system.

Once enabled, only players added to the whitelist can join.
Below are the simple, concrete steps for enabling the whitelist and managing players.

2. Requirements Before You Start

• Access to your server console or in-game OP account.
• Server type: Vanilla, Spigot, Paper, Purpur (works on all).
• Permission to use admin commands.
• Online-mode enabled (recommended).

3. Enabling the Whitelist

You can enable the whitelist in two ways.

Option A - Using a Command (recommended)

Run in console or in-game as OP:

/whitelist on

The whitelist is now active.

Option B - Using the Configuration File

1. Open server.properties
2. Find:

white-list=false

3. Change to:

white-list=true

4. Save the file.
5. Restart the server.

4. Adding Players to the Whitelist

To add a player:

/whitelist add PLAYERNAME

Example:

/whitelist add Notch

The player can now join the server.

5. Removing Players from the Whitelist

To remove a player:

/whitelist remove PLAYERNAME

Example:

/whitelist remove Notch

That player will no longer be able to join.

6. Checking Who Is on the Whitelist

To display all whitelisted players:

/whitelist list

7. Reloading the Whitelist

If you edited the whitelist file manually:

/whitelist reload

This reloads whitelist.json without restarting the server.

8. Automatically Kicking Non-Whitelisted Players

If someone is already online and you enable the whitelist:

/whitelist on

They will be kicked automatically if they are not on the list.

9. Disabling the Whitelist

To turn it off completely:

/whitelist off

After this, everyone can join again.

10. Whitelist File Location

The whitelist is stored in:

/whitelist.json

Each entry contains:

• Username
• UUID

You can edit this file manually when the server is offline.

11. FAQ – Common Problems

Q: Whitelist is ON but players can still join.
A: Check:

• if you are behind BungeeCord / Velocity, whitelist must be enabled on all backend servers,
• if a plugin is overriding the whitelist,
• if the proxy allows connections without whitelist.

Q: Player changed nickname and can’t join.
A: Remove them and add again:

/whitelist remove oldname
/whitelist add newname

Q: Whitelist doesn’t work in offline-mode.
A: In offline-mode, whitelist is name-based only and less secure.
Online-mode is strongly recommended for proper UUID validation.

Q: Can I mass-add players?
A: Yes, by editing whitelist.json manually and then running:

/whitelist reload

12. When You Should Use Whitelist

Whitelist is ideal for:

• private SMP servers,
• RP servers,
• testing servers,
• closed beta servers,
• protection against bots and random joiners.