Server Properties

To unify management of the Minecraft server container, all known server.properties entries can be managed by environment variables. Some mappings provide additional functionality beyond the properties file.

Not all server properties are supported by all versions of Minecraft. Since this image supports a wide range of versions, please consult the server properties documentation for the version you are using.

Managing server.properties

If you prefer to manually manage the server.properties file, set OVERRIDE_SERVER_PROPERTIES to false. Similarly, you can skip the startup script’s creation of server.properties by setting SKIP_SERVER_PROPERTIES to true.

To clear a server property, set the variable to an empty string, such as -e RESOURCE_PACK="". An unset variable is ignored and the existing server property is left unchanged.

To see what server.properties will be used by the server, set DUMP_SERVER_PROPERTIES to true and the contents will be output before the server starts.

OVERRIDE_SERVER_PROPERTIES

boolean

default:"true"

Set to false to manually manage the server.properties file

SKIP_SERVER_PROPERTIES

boolean

default:"false"

Set to true to skip creation of server.properties

DUMP_SERVER_PROPERTIES

boolean

default:"false"

Set to true to output server.properties contents before server starts

SERVER_PROPERTIES_ESCAPE_UNICODE

boolean

default:"auto"

Controls whether unicode characters are escaped as \uXXXX. By default, unicode characters are escaped for Minecraft versions less than 1.20.

Common Properties

Message of the Day

The message of the day, shown below each server entry in the client UI, can be changed with the MOTD environment variable. By default, a message is computed from the server type and version.

MOTD

string

default:"A {TYPE} Minecraft Server powered by Docker"

The server message of the day. Supports formatting codes using § symbol and unicode characters.

The section symbol (§) and other unicode characters are automatically converted to allow formatting codes to be used consistently.

docker run
docker compose

docker run -d -e MOTD="A §l§cMinecraft§r §nserver" ...

environment:
  MOTD: "A §l§cMinecraft§r §nserver"

To produce a multi-line MOTD, embed a newline character as \n:

environment:
  MOTD: |
    line one
    line two
# or
# MOTD: "line one\nline two"

Difficulty

DIFFICULTY

string

default:"easy"

The difficulty level. Valid values: peaceful, easy, normal, hard

docker run -d -e DIFFICULTY=hard ...

Refer to the Minecraft wiki for more information.

Whitelist Players

For public servers, it is very important to consider setting a whitelist of expected players.

WHITELIST

string

Comma or newline separated list of usernames and/or UUIDs to whitelist

WHITELIST_FILE

string

URL or container path to a whitelist file to retrieve/copy into the standard location

EXISTING_WHITELIST_FILE

string

default:"SYNC_FILE_MERGE_LIST"

Behavior when whitelist file already exists. Options:

SKIP: Skip processing when file exists (same as legacy OVERRIDE_WHITELIST=false)
SYNCHRONIZE: Sync users with provided list (same as legacy OVERRIDE_WHITELIST=true)
MERGE: Merge WHITELIST users into existing file
SYNC_FILE_MERGE_LIST: When WHITELIST_FILE provided, overwrite existing; merge WHITELIST users

ENFORCE_WHITELIST

boolean

default:"false"

Enforce whitelist changes immediately when whitelist commands are used

ENABLE_WHITELIST

boolean

default:"false"

Set the white-list property when manually managing the whitelist file

Example

environment:
  WHITELIST: |
    user1
    user2
    user3

For versions prior to 1.7.3, white-list.txt is maintained instead. Only usernames are supported for those versions.

Op/Administrator Players

OPS

string

Comma or newline separated list of usernames and/or UUIDs to grant operator privileges

OPS_FILE

string

URL or container path to an ops file to retrieve/copy into the standard location

EXISTING_OPS_FILE

string

default:"SYNC_FILE_MERGE_LIST"

Behavior when ops file already exists. Options:

SKIP: Skip processing when file exists
SYNCHRONIZE: Sync users with provided list, retaining level and bypassesPlayerLimit
MERGE: Merge OPS users into existing file
SYNC_FILE_MERGE_LIST: When OPS_FILE provided, overwrite existing; merge OPS users

USER_API_PROVIDER

string

default:"playerdb"

API provider for username resolution. Options: playerdb or mojang

Example

environment:
  OPS: |
    user1
    user2
    user3

RCON

RCON is enabled by default to allow for graceful shutdown and backup coordination.

ENABLE_RCON

boolean

default:"true"

Enable RCON support. Disabling removes some features like interactive and color console support.

RCON_PASSWORD

string

RCON password. Randomly generated by default on each startup.

RCON_PASSWORD_FILE

string

Path to file containing RCON password. Recommended for Docker Secrets.

RCON_PORT

number

default:"25575"

RCON port within the container. Do not change unless you have a very good reason.

BE CAUTIOUS OF MAPPING THE RCON PORT EXTERNALLY unless you are aware of all consequences and have set a secure password.

Using Docker Secrets

services:
  mc:
    image: itzg/minecraft-server:latest
    environment:
      EULA: "TRUE"
      RCON_PASSWORD_FILE: /run/secrets/rcon_pass
    secrets:
      - rcon_pass

secrets:
  rcon_pass:
    file: ./rcon_password

Query

ENABLE_QUERY

boolean

default:"false"

Enable the gamespy query protocol

QUERY_PORT

number

default:"25565"

Query port (UDP)

Game Settings

SEED

string

Level seed for world generation. Quote negative values.

MODE

string

default:"survival"

Game mode. Values: creative, survival, adventure, spectator (1.8+)

LEVEL

string

default:"world"

World save name. Maps to level-name server property.

LEVEL_TYPE

string

default:"default"

World generation type. See Minecraft wiki for valid types.

GENERATOR_SETTINGS

json

JSON configuration for world generation. Used with some level types like FLAT.

Superflat Example

environment:
  LEVEL_TYPE: FLAT
  GENERATOR_SETTINGS: >-
    {
        "layers": [
            {"block": "minecraft:bedrock", "height": 1},
            {"block": "minecraft:stone", "height": 2},
            {"block": "minecraft:sandstone", "height": 15}
        ],
        "biome": "minecraft:desert"
    }

Server Icon

ICON

string

URL or container path to server icon image. Automatically downloaded, scaled, and converted.

OVERRIDE_ICON

boolean

default:"false"

Replace existing server-icon.png file

Resource Pack

RESOURCE_PACK

string

URL to custom resource pack

RESOURCE_PACK_SHA1

string

SHA1 checksum of the resource pack

RESOURCE_PACK_ENFORCE

boolean

default:"false"

Enforce the resource pack on clients

Server Port

Only change this if you know what you’re doing. It’s only needed with host-networking, which is rarely required. Use -p port mappings instead.

SERVER_PORT

number

default:"25565"

Server port. Maps to server-port property.

Datapacks

INITIAL_ENABLED_PACKS

string

Comma separated list of datapacks to enable before initial world creation (1.19.3+)

INITIAL_DISABLED_PACKS

string

Comma separated list of datapacks to disable before initial world creation (1.19.3+)

Custom Properties

CUSTOM_SERVER_PROPERTIES

string

Newline delimited name=value pairs for custom server properties used by some mods/plugins

Example

environment:
  CUSTOM_SERVER_PROPERTIES: |
    custom1=value1
    defaultworldgenerator-port=f8c04631-f744-11ec-b260-f02f74b094e0

All Property Mappings

Not all server properties are supported by all versions of Minecraft. Please consult the server properties documentation for your version.

Environment Variable	Server Property
ACCEPTS_TRANSFERS	accepts-transfers
ALLOW_FLIGHT	allow-flight
ALLOW_NETHER	allow-nether
ANNOUNCE_PLAYER_ACHIEVEMENTS	announce-player-achievements
BROADCAST_CONSOLE_TO_OPS	broadcast-console-to-ops
BROADCAST_RCON_TO_OPS	broadcast-rcon-to-ops
BUG_REPORT_LINK	bug-report-link
ENABLE_COMMAND_BLOCK	enable-command-block
ENABLE_STATUS	enable-status
ENFORCE_SECURE_PROFILE	enforce-secure-profile
ENTITY_BROADCAST_RANGE_PERCENTAGE	entity-broadcast-range-percentage
FORCE_GAMEMODE	force-gamemode
FUNCTION_PERMISSION_LEVEL	function-permission-level
GENERATE_STRUCTURES	generate-structures
GENERATOR_SETTINGS	generator-settings
HARDCORE	hardcore
HIDE_ONLINE_PLAYERS	hide-online-players
LOG_IPS	log-ips
MAX_BUILD_HEIGHT	max-build-height
MAX_CHAINED_NEIGHBOR_UPDATES	max-chained-neighbor-updates
MAX_COMMAND_CHAIN_LENGTH	max-command-chain-length
MAX_ENTITY_COLLISION_RADIUS	max-entity-collision-radius
MAX_ENTITY_CRAMMING	max-entity-cramming
MAX_FUNCTION_CHAIN_DEPTH	max-function-chain-depth
MAX_NEIGHBORS	max-neighbors
MAX_PLAYERS	max-players
MAX_TICK_TIME	max-tick-time
MAX_WORLD_SIZE	max-world-size
NETWORK_COMPRESSION_THRESHOLD	network-compression-threshold
ONLINE_MODE	online-mode
OP_PERMISSION_LEVEL	op-permission-level
PAUSE_WHEN_EMPTY_SECONDS	pause-when-empty-seconds
PLAYER_IDLE_TIMEOUT	player-idle-timeout
PREVENT_PROXY_CONNECTIONS	prevent-proxy-connections
PVP	pvp
RATE_LIMIT	rate-limit
REGION_FILE_COMPRESSION	region-file-compression
RESOURCE_PACK_ID	resource-pack-id
RESOURCE_PACK_PROMPT	resource-pack-prompt
SERVER_NAME	server-name
SIMULATION_DISTANCE	simulation-distance
SNOOPER_ENABLED	snooper-enabled
SPAWN_ANIMALS	spawn-animals
SPAWN_MONSTERS	spawn-monsters
SPAWN_NPCS	spawn-npcs
SPAWN_PROTECTION	spawn-protection
STATUS_HEARTBEAT_INTERVAL	status-heartbeat-interval
SYNC_CHUNK_WRITES	sync-chunk-writes
USE_NATIVE_TRANSPORT	use-native-transport
VIEW_DISTANCE	view-distance

Get Started

Server Types

Mod Platforms

Configuration

Mods & Plugins

Versions

Operations

Deployment

Advanced

Managing server.properties

Common Properties

Message of the Day

Difficulty

Whitelist Players

Op/Administrator Players

RCON

Query

Game Settings

Server Icon

Resource Pack

Server Port

Datapacks

Custom Properties

All Property Mappings

Build docs developers (and LLMs) love

Get Started

Server Types

Mod Platforms

Configuration

Mods & Plugins

Versions

Operations

Deployment

Advanced

​Managing server.properties

​Common Properties

​Message of the Day

​Difficulty

​Whitelist Players

​Op/Administrator Players

​RCON

​Query

​Game Settings

​Server Icon

​Resource Pack

​Server Port

​Datapacks

​Custom Properties

​All Property Mappings

Build docs developers (and LLMs) love

Managing server.properties

Common Properties

Message of the Day

Difficulty

Whitelist Players

Op/Administrator Players

RCON

Query

Game Settings

Server Icon

Resource Pack

Server Port

Datapacks

Custom Properties

All Property Mappings