server.properties: complete reference of every option (Minecraft 2026)

The server.properties file lives in the server root and is read exactly once: at startup. Edit a line on a hot server, forget to restart, then wonder why nothing changed. Since 1.20.5 the file has grown new keys, 1.21 added the transfer packet and a couple of security flags. In one reference we walk through every line: what it does, the vanilla default, and what real operators set on SMP, minigames, hardcore and large public projects.

Where the file lives and how it is structured

The file is created on first startup in the same folder as paper.jar or server.jar. Format is trivial: key=value, one pair per line, comments start with #. Keys are lowercase with hyphens, no spaces around =. Encoding is UTF-8 without BOM, line endings LF (if you edit on Windows and then see garbled motd, encoding is the culprit).

The server reads the file once on boot. Any change requires a restart, or on Paper a /minecraft:reload for a subset of fields (most still need a full restart). Unknown keys are ignored after startup, missing keys are written back with default values. Delete the file and vanilla regenerates a fresh one with empty level-seed= and a fresh prompt to accept EULA in eula.txt.

Comments and line order are not preserved: after the first run the file is rewritten in canonical form (alphabetical on vanilla). If you need comments, keep them in a separate note. They will not survive in the actual file.

Network: ports, MTU and anti-proxy

The network block decides how the server listens for incoming connections and how it processes packets.

• server-port is the TCP port, default 25565. You can pick any free port, but if you change it, clients have to specify it explicitly (mc.example.com:25577) or you have to publish a SRV DNS record. Hiding from Shodan scans by changing the port barely helps: attackers sweep ranges anyway.
• server-ip is the interface to bind. Empty by default, which means all interfaces. If your dedicated box has multiple IPs and you want to bind to one, put the IP here. On a single-IP VPS leave empty.
• network-compression-threshold is the packet size in bytes after which zlib compression kicks in. Default 256. Set 512 if you have strong CPU and weak uplink, -1 (disable compression) if you are on LAN or have a 10G uplink and want to save cycles.
• prevent-proxy-connections makes the server probe Mojang API to detect VPNs/proxies on connect. Sounds good, in practice it stalls (synchronous blocking call per join) and does not catch modern residential proxies. Leave false, do filtering at the DDoS layer or in a plugin.
• rate-limit is the maximum packets per second from one client. Default 0 (no limit). Set 300 on a public server to mitigate in-session connection floods.
• enable-status controls whether the server replies to ping requests (Server List Ping). Default true. If you want to hide the server from public trackers, set false, but the player list disappears too.
• hide-online-players was added in 1.18. With true only the player count is sent in Server List Ping, no nicknames. Useful against bots that scrape names for targeted spam or harassment.

World: generation, region format

• level-name is the world folder. Default world. Change to swap between worlds without deleting the old: leave world_old, set level-name=world_new, a fresh world is generated on next boot.
• level-seed seeds world generation. Empty means random. Accepts both numbers and strings (strings are hashed to a long).
• level-type is the generator type. Since 1.19 the format moved to a namespaced ID: minecraft:normal, minecraft:flat, minecraft:large_biomes, minecraft:amplified, minecraft:single_biome_surface. The legacy keys DEFAULT/FLAT/LARGEBIOMES/AMPLIFIED still work via a back-compat mapper, but Mojang prefers the new format.
• generator-settings holds JSON for custom generation (layer list for flat, biome ID for single_biome). Most SMP owners leave it empty.
• generate-structures decides whether villages, strongholds and trail ruins are generated. Default true. Set false if you want a bare world for a survival show or for tests.
• world-creation-seed was added for the new generator pipeline in 1.20+, mirrors level-seed for compatibility with datapacks that read this exact key.
• region-file-compression is the compression algorithm for region files. Since 1.20.5 supports deflate (default), lz4 and none. On large worlds LZ4 gives a +20-30% chunk-load speedup at the cost of +5-10% disk size. If your disk is not NVMe and I/O is weak, switch to lz4.
• max-world-size is world radius in blocks from spawn. Default 29999984 (vanilla cap). Lower it to 5000-10000 for minigame arenas to stop players from drifting off.
• allow-nether controls Nether generation and access. Default true. On skyblock or bedwars usually false.
• spawn-monsters controls hostile mob spawning. Default true. Set false on creative or hub servers.
• spawn-animals controls passive mobs.
• spawn-npcs controls villagers.

Gameplay: mode, difficulty, respawn

• gamemode is the starting mode: survival (0), creative (1), adventure (2), spectator (3). Word or number both accepted.
• force-gamemode resets every player to the configured gamemode on each connect when true. Useful on survival servers when an admin temporarily switched to creative and does not want it to stick.
• difficulty is peaceful, easy, normal or hard. Hardcore is a separate flag.
• hardcore with true makes survival death = ban or forced spectator (depending on settings), no health regen, difficulty pinned at hard. Set once and you cannot easily revert: the world has the hardcore flag inside.
• pvp with false means players cannot directly damage each other. Indirect damage (TNT, fall damage from push blocks) still goes through, plug those holes with plugins.
• allow-flight lets a plugin or item (Elytra, creative) enable flight without anti-cheat kicking. Default false. If you run jetpack/grappling plugins, set true.
• spawn-protection is the radius in blocks around the spawn point where non-ops cannot break or place blocks. Default 16. For SMP without a spawn fortress set 0, for public hubs set 64-128.
• op-permission-level is the starting privilege level of new ops. Range 1 to 4. Default 4 (full access). On large projects set 2 and grant 4 only to the owner: level 4 unlocks /op, /deop, /stop and command-block access.
• function-permission-level is the level for commands inside functions (mcfunction). Default 2.
• default-resource-pack is the URL of the resource pack the server offers to clients (1.20.3+ supports multiple packs through server-resource-pack-prompt and a series of fields).
• require-resource-pack with true kicks clients that refuse to download the pack.
• resource-pack-sha1 is the SHA-1 of the pack archive for integrity check. Mandatory if you want to make sure clients did not get a MITM-tampered pack.

Performance: view-distance, simulation-distance, ticks

This is where the hot settings live. A misjudged view-distance=32 brings down the server with 30+ players online, the right value adds free TPS.

• view-distance is the chunk radius the server sends to the client. Default 10. SMP up to 50 players: 8-10. 100+ players: 6-8. Minigame arena: 4-5 (the map is small anyway).
• simulation-distance is the chunk radius where mobs tick, farms run, crops grow, redstone fires. Introduced in 1.18 as a metric separate from view. Default 10. Set 6-8: players do not interact with farms beyond that anyway, CPU is saved dramatically.
• entity-broadcast-range-percentage is the percentage of view-distance at which the client sees entities (mobs, item frames). Default 100. Drop to 50-70 on a server with laggy entities: visually the player sees fewer of them, network and client load drops.
• max-tick-time is milliseconds a tick can run before the watchdog kills the server. Default 60000 (60 seconds) on vanilla, -1 on Paper (off). If you are not on vanilla and watchdog kills your server in the middle of the night, switch to -1 and chase the lag with /spark.
• max-chained-neighbor-updates caps redstone neighbor cascades per tick. Default 1000000 in 1.21. On SMP where players build huge TNT dupers and redstone conveyors, drop to 100000-300000: long physics chains are cut, lag machines die, normal farms keep working.
• sync-chunk-writes writes chunks synchronously when true (default), async when false. On SSD keep true, async breaks world integrity on a crash. On HDD under heavy load false flattens spikes but real corruption risk.
• entity-tracking-range is hard-coded on vanilla, in paper-world.yml on Paper. It is not in server.properties, do not write it there.

Security: online-mode, secure-profile, whitelist, log-ips, accept-transfers

• online-mode is the most important line in the file. With true the server verifies UUID and session against the Mojang/Microsoft API. With false any client can join under any name. Default true. Set to false ONLY if there is a Velocity/BungeeCord proxy in front of the server with online-mode=true set on the proxy.
• enforce-secure-profile was added in 1.19, relevant in 1.21. With true the client must present a Mojang-signed key for chat messages. Under Bedrock clients via Geyser, turn this off (false), otherwise Bedrock players cannot connect.
• prevent-proxy-connections was already covered in network.
• white-list with true only accepts names listed in whitelist.json. Default false. Must-have for a private SMP.
• enforce-whitelist with true makes the server kick removed players immediately. With false a player removed from the whitelist while online stays in until they log out. Counterintuitive but that is vanilla behavior.
• log-ips was added in 1.20.2. With true (default) the player IP is written to latest.log on every connect. For GDPR friendliness and to reduce leaks, set false. You still get logs for moderation, just without IPs.
• accept-transfers was added in 1.20.5. Allows accepting a transfer packet from another server: a player who ran /transfer on the source server arrives at yours without the usual login dialog. Massive security risk if you do not control the source servers: leave false on a standalone, set true only inside a proxied network where transfer is a lobby feature.
• op-permission-level was already covered under gameplay.
• text-filtering-config is a path to a JSON config for the cloud text filter (Microsoft). Empty by default, not needed.

Query, RCON and admin interfaces

• enable-query is a UDP GameSpy-style protocol that exposes stats (TPS, players, version) to third-party trackers. Default false. Enable only if you actually need to push stats to a monitor: an extra open UDP port is extra attack surface.
• query.port is the UDP query port, default 25565 (same as server-port). Move it to a separate port if enabled.
• enable-rcon is the TCP remote admin protocol. Default false. If you enable it, set a strong rcon.password and firewall the port to admin IPs only. RCON has no TLS: on a public network, tunnel it through SSH or WireGuard.
• rcon.port is the RCON port, default 25575.
• rcon.password is empty by default, an empty password means RCON is effectively disabled even with enable-rcon=true. Use 24+ random characters, do not reuse the hosting password.
• broadcast-rcon-to-ops with true mirrors RCON commands to all ops online. Useful for audit (you see when a command came in from outside).
• broadcast-console-to-ops does the same for console commands.
• enable-jmx-monitoring exposes JVM metrics through JMX. Useful for Prometheus with jmx-exporter. Default false.

MOTD and branding

• motd is the line under the server name in the list. Up to 59 characters per line, two lines split by \n. Colors via \u00A7 plus a code (e.g. \u00A7e for yellow), or legacy & if your Paper has the decoder enabled. JSON format works since 1.16+ via unicode escape, but a plugin is easier (animated MOTD).
• server-icon is actually not a property at all but a server-icon.png 64x64 file in the server root. Five times a year somebody opens .properties, hunts for icon and finds nothing.
• pause-when-empty-seconds was added in 1.21.2. After how many seconds without players the server pauses its tick loop (mobs do not move, time does not pass, IO drops to almost zero). Default 60. On SMP with auto-farms set 0 (do not pause, otherwise farms stop while you are offline). On a public hub set 60-300.
• player-idle-timeout is minutes of inactivity before a player is kicked. Default 0 (do not kick). On a public server with limited slots set 15-30.

Reference table

Option	Default	SMP (50 ppl)	Minigame (200 ppl)	Hardcore	Public hub
online-mode	true	true	true	true	true (false behind proxy)
enforce-secure-profile	true	true	true	true	false (if Geyser)
view-distance	10	8	5	10	6
simulation-distance	10	7	4	8	5
entity-broadcast-range-percentage	100	80	60	100	70
max-players	20	50	200	10	500
spawn-protection	16	0	0	0	64
pvp	true	true	true	true	false
difficulty	easy	hard	normal	hard	easy
hardcore	false	false	false	true	false
allow-nether	true	true	false	true	false
spawn-monsters	true	true	false	true	false
white-list	false	true	false	true	false
enforce-whitelist	false	true	false	true	false
log-ips	true	false	false	false	false
accept-transfers	false	false	true (on lobby)	false	true
enable-rcon	false	true	true	false	true
network-compression-threshold	256	256	512	256	256
rate-limit	0	0	300	0	500
region-file-compression	deflate	deflate	lz4	deflate	lz4
max-chained-neighbor-updates	1000000	300000	1000000	1000000	200000
pause-when-empty-seconds	60	0	60	0	60
op-permission-level	4	2	2	4	2

FAQ

Is online-mode=false safe? A standalone server with online-mode=false is open to any kid who types the nickname Notch: log in, grief spawn, log out. There is exactly one safe scenario: a Velocity/BungeeCord proxy with online-mode=true sits in front of your server, and the backend has false plus a firewall that only accepts the proxy IP. Any other configuration is a wide open door.

Which matters more for TPS, view-distance or simulation-distance? For TPS, simulation-distance. Mob ticks, crop growth and redstone are all gated by it. View-distance loads the network and memory (chunks sent to the client) but not ticks. Drop simulation-distance aggressively (down to 4-6), keep view-distance close to standard.

What do I do with accept-transfers? For a single standalone server with no proxy, leave it false. Turning it on means any third-party server with a /transfer command can fling a player at you with an unfresh session. On proxied networks where you control entry points, enable it only on the lobby server.

Does enforce-secure-profile=true break Geyser/Bedrock? Yes. Geyser players have no Mojang-signed key, so with true the server kicks them with Multiplayer Disabled. On a Java-only server keep true (anti chat-spoof protection). On a hybrid Geyser server set false.

Can I edit server.properties without a restart? On vanilla, no. The file is read once on boot. On Paper, /minecraft:reload re-reads datapacks and a subset of fields (whitelist, ops). Most keys (view-distance, simulation-distance, online-mode, default gamemode) need a full restart. Schedule changes for a low-population window.

Where do parkour/hub options like entity-tracking-range live? Not in server.properties. On Paper they are in paper-world.yml and paper-global.yml, on Spigot in spigot.yml, on vanilla they do not exist at all. server.properties is the bare vanilla config, anything Paper/Spigot/Purpur specific lives in their own files.

A well-tuned server.properties saves hours of debugging and dozens of player tickets. One pass through this list before pushing a server to public closes half the typical issues: lag, bot weirdness, IP leaks, auth holes. Revisit the file after every Minecraft major: since 1.20.5 each release ships two or three new lines, and the defaults on those new options are not always what your server actually wants.