Raspberry Pi Minecraft Server: Complete Setup and Optimization Guide

A Raspberry Pi Minecraft server runs on Pi 4 or Pi 5 with 4GB RAM minimum, Java 21, and PaperMC as the server software. PaperMC outperforms vanilla Minecraft server on Pi hardware because its tick optimization and async chunk loading reduce CPU spikes that cause lag on limited hardware. This guide covers flashing and configuring Bookworm Lite, installing OpenJDK 21 and PaperMC, assigning a static IP and forwarding port 25565, tuning for performance, and running the server as a persistent systemd service with automated backups.

Last tested: Raspberry Pi OS Bookworm Lite 64-bit | May 2025 | Raspberry Pi 4 Model B (4GB) | OpenJDK 21, PaperMC 1.21.4, UFW 0.36

Hardware and OS Preparation for a Raspberry Pi Minecraft Server

Pi 4 (4GB) is the minimum for a usable Raspberry Pi Minecraft server. Pi 4 (8GB) or Pi 5 (8GB) are worth the price difference at classroom or family scale because more RAM means a larger heap allocation and fewer garbage collection pauses. USB SSD or NVMe (Pi 5 via M.2 HAT+) is strongly preferred over SD card. A Minecraft world writes constantly to disk. SD cards degrade under that write pattern and introduce read latency that shows up as chunk-loading lag. See Raspberry Pi 5 NVMe Boot: Complete Setup Guide for NVMe setup before starting this guide if you are using Pi 5.

Hardware checklist: Raspberry Pi 4 (4GB minimum) or Pi 5. 5V/3A USB-C PSU (Pi 4) or 5V/5A USB-C PSU (Pi 5). USB SSD (Pi 4) or NVMe via M.2 HAT+ (Pi 5) for storage. Gigabit Ethernet is required. Do not run a Minecraft server over WiFi. Active cooling: official Pi 5 active cooler or a case fan on Pi 4. The server will sustain high CPU load and passive heatsinks are insufficient for extended sessions.

Flash Raspberry Pi OS Bookworm Lite 64-bit using Raspberry Pi Imager. Do not use the ssh file drop method. It does not work on Bookworm. Set hostname, username, password, and enable SSH in the Imager advanced settings panel before writing. After first boot, update before installing anything:

sudo apt update && sudo apt full-upgrade -y

Expected result: SSH connects using the hostname and username set at flash time. uname -m returns aarch64, confirming 64-bit OS. If you see armv7l, you flashed the 32-bit image; reflash with the 64-bit version before continuing.

Installing Java and the Raspberry Pi Minecraft Server

Install OpenJDK 21. Minecraft 1.20.5 and later require Java 21. Earlier Minecraft versions run on Java 17, but 21 is worth using regardless for JVM improvements that reduce GC pause frequency on the Pi’s constrained heap:

sudo apt install -y openjdk-21-jdk
java -version

Create the server directory and download the current PaperMC build. The correct download URL comes from the PaperMC API. Do not use the deprecated launcher.mojang.com URL, which returns 404 for current versions:

mkdir ~/minecraft && cd ~/minecraft
# Download latest PaperMC 1.21 build (check papermc.io/downloads for current URL)
wget https://api.papermc.io/v2/projects/paper/versions/1.21.4/builds/LATEST/downloads/paper-1.21.4-LATEST.jar \
     -O minecraft_server.jar

Replace 1.21.4 and LATEST with the current version and build number from papermc.io/downloads/paper. The API URL format is stable but the version string must match the current release.

Run the server once to generate configuration files:

java -Xms1G -Xmx2G -jar minecraft_server.jar nogui

The server exits after generating eula.txt and server.properties. Accept the EULA:

sed -i 's/eula=false/eula=true/' eula.txt

Edit server.properties for the key settings that affect both gameplay and Pi performance:

nano server.properties

Set view-distance=6 (default 10 is too high for Pi hardware), max-players=6, gamemode=survival, difficulty=normal, and optionally a level-seed for a specific world. online-mode=true requires players to have a valid Minecraft account; set to false only for a LAN-only server where account authentication is not possible.

Expected result: Running the server again with java -Xms1G -Xmx2G -jar minecraft_server.jar nogui produces a Done line in the console output. The world folder appears in ~/minecraft/. If you see Failed to bind to port, another process is using 25565. Check with sudo ss -tlnp | grep 25565.

Network Configuration and Port Forwarding

For a Raspberry Pi Minecraft server accessible outside your home network, you need a stable local IP and port 25565 forwarded through your router. The simplest approach is a DHCP reservation on the router: log into your router admin page, find the DHCP reservation or static lease section, and assign a fixed IP to the Pi’s MAC address. This requires no Pi-side configuration and survives OS reinstalls.

If your router does not support DHCP reservations, assign a static IP via NetworkManager on the Pi:

sudo nmcli con mod "Wired connection 1" \
  ipv4.addresses 192.168.1.100/24 \
  ipv4.gateway 192.168.1.1 \
  ipv4.dns "8.8.8.8 8.8.4.4" \
  ipv4.method manual
sudo nmcli con up "Wired connection 1"

Adjust the IP and gateway to match your network. Verify the address applied with ip addr show eth0.

Configure port forwarding on your router: find the port forwarding section (often under Advanced or Firewall), set the internal IP to the Pi’s static IP, set internal and external port to 25565, protocol TCP. Save and apply. For players outside your network, your public IP is available at ifconfig.me. Verify the port is open with canyouseeme.org.

Lock down the Pi with UFW:

sudo apt install -y ufw
sudo ufw allow 25565/tcp
sudo ufw limit ssh
sudo ufw enable
sudo ufw status

Expected result: UFW status shows port 25565 ALLOW and SSH LIMIT. From a Minecraft client on the same LAN, add a server using the Pi’s local IP and connect successfully. From outside, players connect using your public IP address with port 25565.

Performance Optimization for a Raspberry Pi Minecraft Server

The Pi 4’s bottleneck is CPU throughput during world generation and mob pathfinding, not RAM once the heap is sized correctly. The tuning below addresses the specific constraints of ARM hardware and PaperMC’s configuration surface.

Java heap sizing. For Pi 4 (4GB), allocate 2GB to the server: -Xms1G -Xmx2G. The initial and maximum values being different forces an early resize on startup. Setting both equal (-Xms2G -Xmx2G) eliminates that resize at the cost of higher idle memory. For Pi 4 (8GB) or Pi 5 (8GB), -Xms2G -Xmx3G leaves enough headroom for the OS. Do not set -Xmx above 3G on a 4GB board; the OS needs at least 1GB to avoid swapping.

server.properties tuning. view-distance=6 is the single most impactful setting. Each additional chunk loaded multiplies entity tick cost. simulation-distance=4 (PaperMC 1.18+) controls how far mobs are active independent of view distance. Set this to 4 to further reduce mob tick load without reducing visible terrain. max-players=6 keeps chunk loading bounded.

PaperMC-specific configuration. PaperMC generates config/paper-world-defaults.yml after first run. The most impactful settings for Pi hardware are entity-activation-range (monsters: 16, animals: 16, misc: 8) and optimize-explosions: true. These are PaperMC config options. They do not belong in server.properties and are silently ignored if added there.

ClearLag plugin. Download the ClearLag JAR from its SpigotMC page and place it in ~/minecraft/plugins/. After server restart, ClearLag removes dropped item entities on a configurable interval and broadcasts a warning before clearing. On a survival server where players drop items frequently, this prevents the entity count from climbing to the point where mob ticks dominate CPU usage.

Monitor live resource usage with htop during a session. The server process should sit at 60-90% of one core under normal load. If it pegs at 100% continuously, reduce view-distance or simulation-distance further. Check the server’s TPS (ticks per second) in-game with the PaperMC command /tps. A reading of 20 TPS is full speed; sustained readings below 15 indicate overload.

Security, Backups, and Automation

Run the Raspberry Pi Minecraft server as a systemd service so it starts on boot and restarts after crashes. Create the unit file, replacing youruser with the username you set at flash time:

sudo tee /etc/systemd/system/minecraft.service <<EOF
[Unit]
Description=Raspberry Pi Minecraft Server
After=network.target

[Service]
User=youruser
WorkingDirectory=/home/youruser/minecraft
ExecStart=/usr/bin/java -Xms1G -Xmx2G -jar minecraft_server.jar nogui
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable --now minecraft

Expected result: systemctl status minecraft shows active (running). After a reboot, the server starts automatically without SSH intervention. journalctl -u minecraft -f streams live server logs.

Automate daily world backups with cron. The server must be stopped or the world saved before archiving to avoid corrupted chunk files:

mkdir -p ~/minecraft/backups
crontab -e

Add this line to back up at 3 AM daily and keep 7 days of backups:

0 3 * * * systemctl stop minecraft && \
  tar -czf ~/minecraft/backups/world-$(date +\%Y-\%m-\%d).tar.gz ~/minecraft/world && \
  systemctl start minecraft && \
  find ~/minecraft/backups -name "world-*.tar.gz" -mtime +7 -delete

Secure SSH with an ed25519 key pair. Run this on your local machine, not the Pi:

ssh-keygen -t ed25519 -C "minecraft-pi"
ssh-copy-id youruser@pi-hostname

Once key authentication works, disable password login:

sudo sed -i 's/#PasswordAuthentication yes/PasswordAuthentication no/' /etc/ssh/sshd_config
sudo systemctl restart ssh

For remote access to the server console without leaving SSH open permanently, Tailscale provides authenticated mesh VPN access with no port forwarding required. See Tailscale Raspberry Pi: Complete Secure Remote Access Guide. For monitoring CPU and memory across sessions, see Grafana InfluxDB Raspberry Pi: Complete Monitoring Stack Setup Guide.

FAQ

How many players can a Raspberry Pi Minecraft server support?

Pi 4 (4GB) with PaperMC and the tuning in this guide handles 4-6 concurrent players comfortably at view-distance=6. Above 6 players, TPS drops during world exploration as chunk generation exceeds what the Pi’s CPU can sustain. Pi 5 (8GB) extends this to 8-10 players for the same reason: faster CPU, not more RAM. Player count is ultimately a CPU constraint, not a memory constraint, once the heap is sized correctly.

Why use PaperMC instead of the vanilla Minecraft server JAR?

PaperMC is a drop-in replacement that adds async chunk loading, configurable entity activation ranges, and the /tps command for real-time performance monitoring. On Pi hardware these matter because the vanilla server processes chunk loading synchronously on the main tick thread, which stalls the entire server during world generation. PaperMC moves this off-thread. It also supports the ClearLag and EssentialsX plugins that are useful for managing a small multiplayer server.

Should I use a USB SSD or microSD card for a Raspberry Pi Minecraft server?

USB SSD is strongly preferred. Minecraft writes chunk data continuously as players explore and build. microSD cards have a finite write endurance and the random write pattern of Minecraft world data degrades them faster than typical OS use. A USB SSD on Pi 4 delivers roughly 200-300 MB/s sequential and far better random write performance than even a fast SD card. For Pi 5, NVMe via the M.2 HAT+ eliminates storage as a bottleneck entirely. A 120GB SSD is sufficient for most world sizes a Pi server would generate.

Is port forwarding required for a Raspberry Pi Minecraft server?

Only for players connecting from outside your local network. Players on the same WiFi or Ethernet network connect using the Pi’s local IP address with no port forwarding needed. For external access, port 25565 must be forwarded from your router to the Pi’s static IP. If you do not want to open a port, Tailscale provides an alternative: all players install Tailscale, join your tailnet, and connect to the Pi’s Tailscale IP. No port forwarding, no public IP exposure, and connections are authenticated.

What Java version should I use for a Raspberry Pi Minecraft server?

OpenJDK 21 for Minecraft 1.20.5 and later. Minecraft 1.20.5 made Java 21 a hard requirement. OpenJDK 17 covers older Minecraft versions and still runs on Bookworm, but if you are running a current server version install 21. Both are available via APT on Bookworm: sudo apt install openjdk-21-jdk -y. If you have both installed, verify the active version with java -version and switch with sudo update-alternatives --config java if needed.

References:

• PaperMC downloads: papermc.io/downloads/paper
• PaperMC configuration documentation: docs.papermc.io
• Minecraft server download (vanilla): minecraft.net/en-us/download/server
• ClearLag plugin: spigotmc.org
• Raspberry Pi Imager: raspberrypi.com/software

---

About the Author

Chuck Wilson has been programming and building with computers since the Tandy 1000 era. His professional background includes CAD drafting, manufacturing line programming, and custom computer design. He runs PidiyLab in retirement, documenting Raspberry Pi and homelab projects that he actually deploys and maintains on real hardware. Every article on this site reflects hands-on testing on specific hardware and OS versions, not theoretical walkthroughs.

Last tested hardware: Raspberry Pi 4 Model B (4GB). Last tested OS: Raspberry Pi OS Bookworm Lite 64-bit. OpenJDK 21, PaperMC 1.21.4, UFW 0.36.

---