How to Whitelist Players on Your Minecraft Server (Complete Guide)

Your server IP ends up in a Discord channel with 500 members. Within an hour, random players are logging in, someone has already punched a hole in the spawn building, and your regulars are asking what happened. You kick the griefers, but more keep coming.

This is exactly what the whitelist exists to solve.

A whitelist flips the default access model: instead of "everyone can join unless banned," your server becomes "nobody can join unless explicitly allowed." For private SMPs, friend groups, and communities that value their builds, the whitelist is the first and best line of defense.

This guide covers not just the basic /whitelist add command, but the entire player management system — whitelist, operators, bans, and the JSON files that store it all. By the end, you will understand how these pieces fit together instead of copy-pasting commands and hoping for the best.

Enabling the Whitelist

The whitelist is disabled by default on new Minecraft servers. You have two ways to turn it on:

Option 1: From the console or in-game as an op

/whitelist on

This takes effect immediately. Anyone not on the whitelist gets disconnected the moment you run the command.

Option 2: In server.properties

Open server.properties in your control panel's file manager or via FTP, and change:

white-list=false

to:

white-list=true

Then restart the server. The property name uses a hyphen (white-list), not the command name format.

Once enabled, the server checks every connection attempt against the whitelist. If the player's UUID is not in whitelist.json, they see a "You are not whitelisted on this server!" message and get disconnected.

Adding and Removing Players

With the whitelist on, you add players by username:

/whitelist add PlayerName

The server looks up the UUID for that username from Mojang's API (assuming you are running in online mode) and stores both in whitelist.json. The player can now connect.

To remove access:

/whitelist remove PlayerName

The player is removed from the whitelist file. If they are currently online, they remain connected until they log out — the whitelist is only checked at connection time.

To see everyone currently whitelisted:

/whitelist list

If you have edited the JSON file manually while the server is running, reload it:

/whitelist reload

Whitelisting Offline Players

One quirk: /whitelist add requires the player to have a valid Mojang account with that exact username. If your friend has never purchased Minecraft, or their username has a typo, the command fails with "Player does not exist."

For offline-mode servers (which skip Mojang authentication), you will need to edit the JSON file directly. More on that below.

Understanding whitelist.json

Every whitelist entry lives in whitelist.json at the root of your server directory. Here is what it looks like:

[
  {
    "uuid": "f8d5e4c7-3a2b-1c9d-8e7f-6a5b4c3d2e1f",
    "name": "PlayerOne"
  },
  {
    "uuid": "a1b2c3d4-5e6f-7a8b-9c0d-e1f2a3b4c5d6",
    "name": "PlayerTwo"
  }
]

Each entry has two fields:

The UUID is the real key. If a player changes their username, they remain whitelisted because their UUID stays the same. The name field does not auto-update, though — it will still show their old name until you remove and re-add them.

Manual Editing

You can edit whitelist.json directly. This is useful for bulk-adding players or for offline-mode servers where Mojang lookups do not work.

A few rules:

1. The server must be stopped, or you must run /whitelist reload afterward.
2. UUIDs must be valid format (8-4-4-4-12 hex digits with hyphens).
3. For offline-mode servers, the UUID is derived from the username itself using a specific algorithm — it is not the same as the player's Mojang UUID. Tools like NameMC cannot help you here; you need an offline UUID generator.
4. The JSON must be valid. A missing comma or bracket will cause the server to fail to load the whitelist.

The Offline Mode Problem

If your server runs in offline mode (online-mode=false), the UUID for each player is generated locally from their username. This means:

• The same username gives the same UUID, but it will not match their Mojang account.
• If someone joins with username "Steve" on your offline server, then you later switch to online mode, they will have a different UUID and lose their whitelist entry (and their inventory, builds tied to that UUID, etc.).

Mixing online and offline mode is messy. If you are running a private SMP with friends, online mode is strongly recommended.

Operators and Permission Levels

The whitelist controls who can connect. Operator status controls what they can do once connected.

/op PlayerName

This grants the player operator privileges. By default, ops get permission level 4 — full access to every command including /stop, /op, /ban, and /whitelist itself.

Permission Levels Explained

Minecraft has four operator permission levels, set in ops.json:

To set a specific level, edit ops.json:

[
  {
    "uuid": "f8d5e4c7-3a2b-1c9d-8e7f-6a5b4c3d2e1f",
    "name": "PlayerOne",
    "level": 4,
    "bypassesPlayerLimit": true
  }
]

The bypassesPlayerLimit field lets this player join even when the server is full.

Should Ops Be Whitelisted?

Yes. Being an operator does not automatically add you to the whitelist. If you /op someone without whitelisting them, they cannot connect while the whitelist is active.

The reverse is also true: whitelisting someone does not make them an op. Whitelist and op are completely independent systems. For a typical private SMP:

• All regular players: whitelisted, not op.
• Admins: whitelisted and op (level 3 or 4).
• You: whitelisted and op level 4.

Bans and Kicks

Sometimes the whitelist is not enough. Someone you trusted turns out to be a problem. That is what bans are for.

Kick: Immediate Removal

/kick PlayerName reason

The reason is optional but helpful — the player sees it when disconnected. Kicks are temporary; the player can rejoin immediately unless you have other protections in place.

Use kicks for minor issues: someone is being annoying, or you need them to relog to apply a change.

Ban: Permanent Block

/ban PlayerName reason

This disconnects the player and adds them to banned-players.json. They cannot rejoin until unbanned.

/pardon PlayerName

Removes the ban.

IP Bans

/ban-ip 192.168.1.100 reason

Blocks an IP address entirely. This catches players who create new accounts to evade bans. But it also catches legitimate players on shared networks (university dorms, VPNs), so use it cautiously.

To list or remove IP bans:

/banlist ips
/pardon-ip 192.168.1.100

Whitelist vs Ban: When to Use Each

A whitelist and a ban are not the same thing, even though both prevent joining.

If your server is whitelisted, removing someone from the whitelist achieves the same practical effect as banning them — they cannot join. The difference is intent: whitelist removal says "you are no longer invited," while a ban says "you are explicitly prohibited." Bans also show a reason message to the player.

For more details on the commands themselves, see the console commands cheat sheet.

Plugins for Advanced Access Control

The vanilla whitelist, op, and ban system is sufficient for small private servers. When you need more granular control, plugins step in.

LuckPerms: Granular Permissions

LuckPerms replaces the binary op system with permission nodes. Instead of "op" or "not op," you define exactly which commands and features each player or group can access.

Example use case: you want certain players to use /tp without giving them full admin access. With vanilla ops, that is impossible — level 2 includes a bundle of commands. With LuckPerms, you grant only the minecraft.command.teleport permission.

LuckPerms also supports permission groups, inheritance, temporary permissions, and context-based permissions (e.g., different permissions in different worlds).

Discord Whitelist Integration

Several plugins connect your whitelist to Discord:

• DiscordSRV includes a whitelist sync feature where users link their Discord account to their Minecraft account, and whitelisting happens automatically when they join your Discord server or receive a role.
• Discord Whitelist is a simpler single-purpose plugin that manages the whitelist via Discord bot commands.

This is especially useful for community servers where you vet players through a Discord application process. Once approved, their Minecraft account is whitelisted without an admin manually running commands.

Whitelist on BungeeCord/Velocity Networks

If you run a proxy network with BungeeCord or Velocity, the whitelist situation becomes more complex. Each backend server has its own whitelist, but players connect through the proxy.

Most networks handle this by:

1. Disabling vanilla whitelists on backend servers.
2. Using a proxy-level whitelist plugin (like BungeeWhitelist or a permission plugin with proxy support).
3. Keeping backend servers in offline mode behind the proxy (since the proxy handles authentication).

This setup is beyond the scope of a vanilla whitelist guide, but if you are scaling to a network, you will need to rethink your access control strategy.

Quick Reference

Related Guides

• Minecraft Server Console Commands Cheat Sheet — full reference for every server command, organized by category.
• How to Make a Minecraft SMP Server in 2026 — complete setup guide for private survival multiplayer servers.
• Minecraft Server Hosting 101 — beginner guide to server types, hosting options, and what to look for.
• Best Minecraft Server Plugins 2026 — the plugins mentioned here plus 18 more essentials.
• BungeeCord vs Velocity — choosing a proxy if you scale beyond a single server.
• A Complete Tour of the Swelis Control Panel — file manager, console, and other tools for managing your server.

If you want a server where the whitelist and console are already accessible from a browser — no SSH, no FTP client, no port forwarding — you can spin one up on Swelis in about two minutes.