/whitelist

Manages the server whitelist. When enabled, only whitelisted players can join the server.

Overview

Manages the server whitelist. When enabled, only whitelisted players can join the server. In vanilla Minecraft Java Edition it is one of the server commands and has been available since version 1.0.

It is invoked as /whitelist [] and accepts one required argument () and one optional argument ([targets]).

Players already connected are not kicked when the whitelist is enabled. Use 'enforce-whitelist=true' in server.properties to kick non-whitelisted players when the whitelist is reloaded.

Enabling the whitelist does not kick players who are already online. Set enforce-whitelist=true in server.properties so a reload removes anyone not listed.

Syntax & Arguments

/whitelist <add|list|off|on|reload|remove> [<targets>]

The full syntax is /whitelist []. Angle brackets < > mark required arguments and square brackets [ ] mark optional ones; a vertical bar | between words means you pick exactly one of those literals. You must always supply . The argument [targets] may be omitted, in which case the documented default applies.

action: Required, of type a literal. on/off = enable/disable whitelist; add/remove = manage players; list = show whitelisted players; reload = reload from file.
targets: Optional, of type a game_profile. The player for add/remove actions.

Parameters

Name	Type	Required	Description
action	literal	Required	on/off = enable/disable whitelist; add/remove = manage players; list = show whitelisted players; reload = reload from file.
targets	game_profile	Optional	The player for add/remove actions.

Examples

The 3 examples below are ready to copy and adapt. For instance, /whitelist on enables the server whitelist. Each example varies the arguments to show a different real use of /whitelist; read the note under every snippet to see exactly what changes.

/whitelist on

Enables the server whitelist.

/whitelist add Steve

Adds Steve to the whitelist.

/whitelist list

Displays all whitelisted players.

Permission Level & Requirements

/whitelist sits at permission Level 3 - Admin, which means it needs permission level 3 (administrator).

Requires level 3.

This reference describes the Java Edition 1.21 form of the command; Bedrock Edition may use slightly different argument formats.

Common Mistakes

Turning on the whitelist without adding yourself first, you may lock yourself out if you disconnect.
Not using /whitelist reload after manually editing whitelist.json, changes from file edits do not apply until reloaded.

Notes

Players already connected are not kicked when the whitelist is enabled. Use 'enforce-whitelist=true' in server.properties to kick non-whitelisted players when the whitelist is reloaded.

Related Commands

If /whitelist is part of your toolkit, the commands below are the ones you will most often reach for alongside it: /op, /ban, and /kick. They cover closely related tasks, so the links above jump straight to each one.

/op

/ban

/kick

Frequently Asked Questions about /whitelist

What does the /whitelist command do in Minecraft?

Manages the server whitelist. When enabled, only whitelisted players can join the server. It belongs to the server command group and was added in Java Edition 1.0.

What is the correct syntax for /whitelist?

/whitelist []. The required argument is action, and the optional one is targets.

What permission level does /whitelist need?

It requires permission Level 3 - Admin. On a server the player must be an operator at that level, or have cheats enabled in single-player.

What is a common mistake when using /whitelist?

Turning on the whitelist without adding yourself first, you may lock yourself out if you disconnect.

Can you give an example of /whitelist in use?

Yes. /whitelist add Steve — adds Steve to the whitelist.

Need a Minecraft server?

Try these commands on Astroworld or host your own server.

Try Astroworld Hosting