What this page covers
Everything here is written for a Minecraft: Java Edition dedicated server, and every command on this page is marked "Dedicated server" in the wiki's command documentation - Java Edition dedicated servers only, not ordinary singleplayer. Bedrock Edition is out of scope: there the command is /allowlist (with on/off not implemented), the file is allowlist.json, ops live in permissions.json, and the equivalent server.properties key is allow-list.
Permission levels: everything here is level 3
All eight commands on this page - /whitelist, /op, /deop, /ban, /ban-ip, /banlist, /pardon, /pardon-ip - require permission level 3 in Java Edition. Levels are incremental: a player at level n can use everything open to any lower level. Java Edition defines four:
| Level | Name | What it unlocks |
|---|---|---|
| 1 | Moderator | Can bypass spawn protection. |
| 2 | Gamemaster | More commands: command blocks, copying NBT with F3+I, the F3+F4 game-mode switcher, changing or locking the difficulty, the "Operator Utilities" creative tab, and target selectors in commands like /tell. |
| 3 | Admin | "Commands related to multiplayer management are available" - this is the level the whitelist, op and ban commands require. |
| 4 | Owner | "All commands are available, including commands related to server management" - for example /stop and /save-all. |
On a private server, most of these commands get typed at the server console. The console can run every command, including the level-4 server-management commands like /stop, without anyone being opped - the wiki's Commands page states that "When executed by the server, or a script, the command is available no matter whether cheats are enabled".
The whitelist: /whitelist and whitelist.json
Java Edition gives the whitelist six subcommands:
| Command | What it does |
|---|---|
/whitelist add <targets> |
Adds players to the whitelist. Players do not need to be online to be added or removed. |
/whitelist remove <targets> |
Removes players from the whitelist. |
/whitelist list |
Lists the whitelisted players. |
/whitelist on / /whitelist off |
Enables or disables the whitelist. |
/whitelist reload |
"Refreshes the profile list from disk, used when whitelist.json has been modified outside of Minecraft." |
One Java-specific behaviour worth knowing before you troubleshoot a lockout: Java Edition ops can connect even if not whitelisted. (Bedrock players must be whitelisted regardless of op status, but Bedrock is outside this page's scope.)
The list itself is a file, whitelist.json, in the server's working directory - the server root. Each Java entry has two fields: uuid, "The UUID of the player, in hyphenated hexadecimal format" - dashes included - and name. In offline mode, the server checks offline UUIDs derived from usernames.
If you edit whitelist.json by hand while the server is running, the change is not picked up on its own: "When editing the file manually while the server is running, the command /whitelist reload needs to be used."
white-list versus enforce-whitelist
Two server.properties keys whose names ask to be confused. The exact spelling white-list (boolean) is the one that enables the whitelist: "With a whitelist enabled, users not on the whitelist cannot connect." The exact spelling enforce-whitelist (boolean, default false) does not enable anything - it decides what happens to players who are already online and not on the whitelist when the whitelist is reloaded: with false they are not kicked, with true they are kicked.
One default has changed recently, and older guides have not caught up: as of Java 26.3 (snapshot 2), white-list is now true by default - "The white-list property is now true by default." Servers on older versions default to false, so read the file in front of you rather than trusting either memory.
Ops do not need a whitelist.json entry: an operator is whitelisted by op status itself, with no need to add them to the file as well.
/op, /deop and ops.json
The syntax is short: /op <targets> grants operator status and /deop <targets> revokes it. Both require permission level 3 and both are dedicated-server commands. Granting op writes the player into ops.json with the default op permission level from server.properties.
An ops.json entry has four fields: uuid (hyphenated hexadecimal), name, level (the operator's permission level, an integer that defaults from op-permission-level) and bypassesPlayerLimit (a boolean). The levels themselves are Java's 1-4 as set by op-permission-level - documented as an integer (0-4) whose default file value is 4, with the description "The default permission level for ops when using /op": the level written into ops.json when someone is opped.
bypassesPlayerLimit is the one field worth setting deliberately on a friends server: true lets the op join even when the server is full (max-players reached), though such players still count toward the limit.
Bans: /ban, /ban-ip, /banlist, /pardon, /pardon-ip
All five ban commands require permission level 3 and are dedicated-server commands:
| Command | What it does |
|---|---|
/ban <targets> [<reason>] |
Bans players from the server, with an optional reason. |
/ban-ip <target> [<reason>] |
Bans an IP address, or the IP address an online player is connecting from - the target is the address itself or the name of an online player. |
/banlist [ips|players] |
The server's ban list, with ips or players selecting which entries are shown. |
/pardon <targets> |
Lifts a ban from banned-players.json. |
/pardon-ip <target> |
Lifts a ban from banned-ips.json. |
The /ban-ip target is a single word, which is why an IPv6 address cannot be banned this way - the wiki's tracker note for that is MC-97885.
The optional reason on /ban and /ban-ip is a greedy message; when it is omitted the default is Banned by an operator. The wiki describes it as the "Message to display to the banned player, to other operators, and in the server logs" - it is visible in all three places. The ban list also overrides the whitelist: anyone on it is blocked from connecting, whatever the whitelist says.
Bans are stored in the server folder as two JSON files. Entries in banned-players.json carry the fields uuid, name, created, source, expires and reason - for example a created value of 2020-09-04 10:40:20 +0200 and expires set to forever. Entries in banned-ips.json carry ip, created, source, expires and reason. A citation note on those field lists: they are documented today on the German-language edition of the Minecraft Wiki's command pages; the English command pages name both files but not their fields. A ban ends with /pardon (or /pardon-ip) "or manually removing it from the banned-players.json". And if your server predates 1.7.6: since 1.7.6 the server converts an old banned-players.txt into the .json file and renames the old file to banned-players.txt.converted.
Paper: no difference found
PaperMC's getting-started documentation (page last updated September 18, 2026) records no differences from vanilla for any of this: not for /whitelist, /op, /deop, /ban, /ban-ip, /banlist, /pardon or /pardon-ip, not for whitelist.json, ops.json, banned-players.json or banned-ips.json, and not for the white-list, enforce-whitelist or op-permission-level keys. Everything on this page works the same on Paper as on a vanilla dedicated server.
Access control is one step of running the server, and the rest is covered elsewhere on this site: how to make a Minecraft server for friends walks the whole setup, the server.properties reference covers white-list, enforce-whitelist and op-permission-level in full, and password-protecting a game server covers the same problem from a different angle.
ForgeWorld Gaming current order availability: Minecraft (Paper, Vanilla and Forge) Standard: 8–56 player slots at CA$9.89–CA$69.23/month; Terraria Standard: 4–24 player slots at CA$8.99–CA$16.99/month; Valheim Standard: 3–10 player slots at CA$11.99–CA$17.99/month; Garry’s Mod Standard: 8–56 player slots at CA$9.89–CA$69.23/month; Factorio Standard: 8–24 player slots at CA$9.99–CA$13.99/month; Palworld Standard: 4–8 player slots at CA$12.99–CA$16.99/month; Enshrouded Standard: 4–6 player slots at CA$11.99–CA$13.99/month; Satisfactory Standard: 4–6 player slots at CA$14.99–CA$18.99/month; Conan Exiles Standard: 8 player slots at CA$15.99/month; 7 Days to Die Standard: 4–8 player slots at CA$10.99–CA$15.99/month; Rust Standard: 50 player slots at CA$19.99/month; Project Zomboid Standard: 8 player slots at CA$13.99/month; ARK Standard: 10 player slots at CA$19.99/month. Other game orders and other sizes and qualities are temporarily paused. Hosted in Chicago, Illinois, United States. Prices are in Canadian dollars, with no setup fee and cancel any time. Your server is set up automatically after payment. Check the current Minecraft availability, Terraria availability, Valheim availability, Garry’s Mod availability, Factorio availability, Palworld availability, Enshrouded availability, Satisfactory availability, Conan Exiles availability, 7 Days to Die availability, Rust availability, Project Zomboid availability and ARK availability, or browse game availability before planning a purchase.