Skip to main content
This page documents the core environment variables required to run and configure the Docker Minecraft Server.

​
Essential Variables

​
EULA

​
EULA
string
required
You MUST set this to TRUE to accept the Minecraft End User License Agreement.
The server will not start without accepting the EULA. Always include -e EULA=TRUE in your commands and container definitions.
docker run -d -it -p 25565:25565 -e EULA=TRUE itzg/minecraft-server

​
Server Type and Version

​
TYPE
string
default:"VANILLA"
The server type to run. See the Server Types documentation for all available options.Common values:
  • VANILLA - Official Minecraft server
  • PAPER - Paper server
  • FORGE - Forge modded server
  • FABRIC - Fabric modded server
  • SPIGOT - Spigot server
  • BUKKIT - Bukkit server
​
VERSION
string
default:"LATEST"
The Minecraft version to install. Can be:
  • LATEST - Latest stable release
  • SNAPSHOT - Latest snapshot
  • Specific version like 1.20.4
  • Version range like 1.20 for latest 1.20.x
Example
environment:
  TYPE: PAPER
  VERSION: "1.20.4"

​
User and Group Settings

By default, the container runs the Minecraft server as user ID 1000 and group ID 1000.
​
UID
number
default:"1000"
The Linux user ID to run the server as
​
GID
number
default:"1000"
The Linux group ID to run the server as
User switching is skipped if the --user/-u argument is passed to docker run or user is set on the compose service.
Example
environment:
  UID: 1001
  GID: 1001

​
Memory Configuration

By default, the image sets both initial and maximum Java heap limits to 1 GB.
​
MEMORY
string
default:"1G"
Sets both initial (Xms) and max (Xmx) memory heap settings.Supports formats:
  • Absolute: 1G, 2048M, 512M
  • Percentage: 50%, 75%
​
INIT_MEMORY
string
Independently sets the initial heap size (overrides MEMORY for Xms)
​
MAX_MEMORY
string
Independently sets the max heap size (overrides MEMORY for Xmx)
environment:
  MEMORY: 2G
Percentage-based heap sizing uses -XX:InitialRAMPercentage for INIT_MEMORY and -XX:MaxRAMPercentage for MAX_MEMORY.
To let the JVM calculate heap size from the container’s memory limit, unset MEMORY: 
docker run -d -e MEMORY="" ...
Memory settings only control Java heap limits. Container resource requests should account for non-heap usage. An extra 25% is a general best practice.

​
Timezone Configuration

​
TZ
string
default:"UTC"
Set the timezone to match your locale. Use standard timezone names like America/New_York or Europe/London.
docker run -d -e TZ=Europe/London ...

​
Locale Settings

​
LC_ALL
string
default:"en_US.UTF-8"
System locale setting. Set in the Dockerfile and generally should not be changed.

​
Data Directory

The Minecraft server stores all data in the container’s /data directory.
Always mount a volume to /data to persist your world saves, configurations, and other server data.
docker run -d \
  -v /path/on/host:/data \
  -e EULA=TRUE \
  itzg/minecraft-server

​
Logging Options

​
LOG_TIMESTAMP
boolean
default:"false"
Include timestamps in init logs (logs before the Minecraft server starts)
​
DEBUG
boolean
default:"false"
Enable debug logging for container startup diagnostics
Example
[init] 2022-02-05 16:58:33+00:00 Starting the Minecraft server...

​
Server Behavior

​
SETUP_ONLY
boolean
default:"false"
Setup server files and stop before launching the server process. Useful for host-attached data directories.
​
FORCE_REDOWNLOAD
boolean
default:"false"
Force re-download of the server file. Works with VANILLA, FORGE, BUKKIT, SPIGOT, PAPER, CURSEFORGE, SPONGEVANILLA types.
Example
environment:
  TYPE: PAPER
  FORCE_REDOWNLOAD: "true"

​
Server Shutdown

​
STOP_DURATION
number
default:"60"
How long (in seconds) to wait for the server process to gracefully finish after sending the stop command
​
STOP_SERVER_ANNOUNCE_DELAY
number
Number of seconds to delay after posting shutdown announcement to allow players to finish activities
The Docker stop grace period must be longer than the announce delay. Increase it using the -t option or set stop_grace_period in compose.
Bypass the announce delay by sending SIGUSR1: 
docker stop --signal SIGUSR1 mc
# or
docker compose kill --signal SIGUSR1

​
Console Options

​
CONSOLE
boolean
default:"true"
Some older Spigot versions (pre-1.14) require --noconsole when detaching stdin. Set to false for those versions.
​
GUI
boolean
default:"true"
Explicitly disable GUI. Some older servers get confused and think GUI is enabled.
When RCON is enabled (default) and TTY is enabled, some server types output colorized logs and provide interactive console. Access with docker attach and detach using Control-P, Control-Q.

​
Network and Proxy

​
PROXY
string
HTTP/HTTPS proxy host:port
​
PROXY_HOST
string
Proxy host (alternative to PROXY)
​
PROXY_PORT
string
Proxy port (alternative to PROXY)
​
PROXY_NON_PROXY_HOSTS
string
Pipe-delimited list of hosts to exclude from proxying

​
Health Monitoring

​
SERVER_HOST
string
default:"localhost"
Host address for health monitoring
​
SERVER_PORT
number
default:"25565"
Port number for health monitoring (not the same as the server port mapping)

​
Extra Arguments

​
EXTRA_ARGS
string
Additional arguments passed to the server JAR file (arguments after the filename)
Example
environment:
  EXTRA_ARGS: "--world-dir /worlds"

​
Custom Server JAR

​
CUSTOM_SERVER
string
URL or container path to a custom server JAR. Requires TYPE=CUSTOM.
Example
environment:
  TYPE: CUSTOM
  CUSTOM_SERVER: https://example.com/my-server.jar
The JAR is only downloaded if it doesn’t exist in /data. To upgrade, stop the container, remove the file, and restart.

​
Complete Example

compose.yaml
services:
  mc:
    image: itzg/minecraft-server:latest
    pull_policy: daily
    tty: true
    stdin_open: true
    ports:
      - "25565:25565"
    environment:
      # Required
      EULA: "TRUE"
      
      # Server Type & Version
      TYPE: PAPER
      VERSION: "1.20.4"
      
      # Resources
      MEMORY: 4G
      
      # User Settings
      UID: 1000
      GID: 1000
      
      # Timezone
      TZ: America/New_York
      
      # Logging
      LOG_TIMESTAMP: "true"
      
    volumes:
      - ./data:/data
    restart: unless-stopped

Build docs developers (and LLMs) love

Get started for freeTalk to us