How to Run a Minecraft Server on Raspberry Pi with Docker

Running your own Minecraft server at home gives you full control over your world, your rules, and who can join. A Raspberry Pi is a surprisingly capable host for a small Minecraft server, and using Docker makes the setup and maintenance much simpler. In this guide, we will use the itzg/minecraft-server Docker image to get a Minecraft Java Edition server running on your Pi.

What You Need

A Raspberry Pi 4 or 5 with at least 4GB of RAM (8GB recommended)
Raspberry Pi OS (64-bit) installed
Docker and Docker Compose installed -- see our Docker setup guide
A stable network connection (wired Ethernet recommended)
Minecraft Java Edition on your computer to connect to the server

Step 1: Create the Docker Compose File

Bash

mkdir ~/minecraft-server && cd ~/minecraft-server
nano docker-compose.yml

Paste the following configuration:

YAML

version: '3.8'

services:
  minecraft:
    image: itzg/minecraft-server:latest
    container_name: minecraft-server
    restart: unless-stopped
    ports:
      - "25565:25565"
    environment:
      EULA: "TRUE"
      TYPE: "PAPER"
      VERSION: "LATEST"
      MEMORY: "2G"
      MAX_PLAYERS: "10"
      DIFFICULTY: "normal"
      MODE: "survival"
      MOTD: "Raspberry Pi Minecraft Server"
      VIEW_DISTANCE: "7"
      SPAWN_PROTECTION: "0"
      ENABLE_COMMAND_BLOCK: "true"
      TZ: "America/New_York"
    volumes:
      - ./data:/data
    stdin_open: true
    tty: true

Key environment variables: EULA must be TRUE to accept the Minecraft EULA. TYPE: PAPER uses PaperMC, which is optimized for performance on low-power hardware. MEMORY: 2G allocates 2GB of RAM -- do not go above 2G on a 4GB Pi, or 4G on an 8GB Pi. VIEW_DISTANCE: 7 reduces the default from 10 to improve performance.

Step 2: Start the Server

Bash

docker-compose up -d

The first startup takes several minutes as the server downloads PaperMC and generates the world. Follow the progress with:

Bash

docker logs -f minecraft-server

Wait until you see Done! For help, type "help" before connecting. Press Ctrl+C to stop following logs without stopping the server.

Step 3: Connect from Minecraft

Open Minecraft Java Edition, click Multiplayer, then Add Server:

Server Name: Whatever you like (e.g., "Pi Server")
Server Address: <your-pi-ip>:25565

Replace <your-pi-ip> with your Raspberry Pi's IP address. Click Done, select the server, and click Join Server.

Step 4: Server Management

Access the server console to run commands:

Bash

docker exec -i minecraft-server rcon-cli

From the rcon-cli console, you can manage your server:

Code

op YourMinecraftUsername
whitelist on
whitelist add FriendUsername
difficulty hard
gamemode creative PlayerName
time set day

To enable a whitelist permanently, add WHITELIST_ENABLED: "true" to the environment variables in your compose file.

Step 5: Performance Tuning

If players experience lag, lower the view distance in docker-compose.yml:

YAML

VIEW_DISTANCE: "5"

Then restart the server:

Bash

docker-compose down && docker-compose up -d

Monitor resource usage with docker stats minecraft-server. If memory is tight, reduce MEMORY, MAX_PLAYERS, or VIEW_DISTANCE.

Step 6: Backups and Updates

Stop the server before backing up to avoid corrupted chunk data:

Bash

docker-compose stop
cp -r ~/minecraft-server/data ~/minecraft-backup-$(date +%Y%m%d)
docker-compose start

To update to the latest Minecraft version:

Bash

cd ~/minecraft-server
docker-compose pull
docker-compose down
docker-compose up -d

Since VERSION is set to LATEST, the image will download the newest PaperMC build on the next startup.

Troubleshooting

Server takes a long time to start: The first boot generates the world, which is CPU-intensive on a Pi. Subsequent starts are much faster.
Players experience lag: Lower VIEW_DISTANCE to 5, reduce MAX_PLAYERS, and make sure you are using TYPE: "PAPER".
Cannot connect: Verify the server has fully started with docker logs minecraft-server. Ensure port 25565 is not blocked by a firewall.
Out of memory errors: Reduce the MEMORY setting. The OS needs RAM too, so never allocate all available memory to Minecraft.
World corruption after power loss: Always stop the server gracefully with docker-compose stop before shutting down the Pi.

Conclusion

With Docker and the itzg/minecraft-server image, running a Minecraft server on a Raspberry Pi is straightforward. The PaperMC server type keeps things running smoothly on limited hardware, and Docker makes updates and management painless. For a small group of friends or a family server, the Raspberry Pi is a great low-power, always-on Minecraft host.