How to Run a Minecraft Server Headless on Linux

Why Run a Minecraft Server Headless on Linux?

Most dedicated servers and VPS instances run Linux without a desktop environment. Running your Minecraft server headless on Linux means you operate it entirely from the command line over SSH, no monitor, no GUI, no wasted resources on a graphical desktop. This is how every serious Minecraft host operates, and it is the most resource-efficient way to run a server because every megabyte of RAM and every CPU cycle goes to the game instead of rendering a desktop you never look at.

A headless setup also makes remote management trivial. You SSH in from your laptop, phone, or another server, run your commands, and disconnect, while the Minecraft server keeps running in the background. This guide walks you through the complete process from a fresh Linux box to a running, persistent Minecraft server headless Linux instance.

Prerequisites

• A Linux server (Ubuntu 22.04/24.04, Debian 12, or Rocky Linux 9 are all solid choices)
• SSH access with a non-root user that has sudo privileges
• At least 2 GB of RAM (4 GB+ recommended for Paper with plugins)
• Java 21 or newer installed

Installing Java 21

Paper 1.21+ requires Java 21. Install it with your package manager:

# Ubuntu / Debian
sudo apt update
sudo apt install openjdk-21-jre-headless -y

# Rocky / AlmaLinux / Fedora
sudo dnf install java-21-openjdk-headless -y

# Verify
java -version

The -headless package variant skips GUI libraries, which is exactly what you want on a server without a display.

Downloading and Configuring the Server

Create a dedicated directory and download your server jar. We recommend Paper for the best performance, but this works with any server type.

mkdir -p ~/minecraft-server && cd ~/minecraft-server
# Download the latest Paper build (check papermc.io for the current URL)
curl -o server.jar https://api.papermc.io/v2/projects/paper/versions/1.21.4/builds/LATEST/downloads/paper-1.21.4.jar

Run the server once to generate the EULA and config files:

java -Xms2G -Xmx2G -jar server.jar --nogui

The --nogui flag is critical for headless operation, it tells the server not to attempt opening a graphical console window. Without it, the process will crash on a system with no display server. Accept the EULA:

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

Running in the Background with screen

screen is the simplest way to keep a process running after you disconnect from SSH. Install it if it is not already present:

sudo apt install screen -y   # Debian/Ubuntu
sudo dnf install screen -y   # Rocky/Fedora

Start a named screen session and launch the server inside it:

screen -S minecraft
cd ~/minecraft-server
java -Xms2G -Xmx4G -jar server.jar --nogui

To detach from the session without stopping the server, press Ctrl+A then D. You can now close your SSH connection safely. To reattach later:

screen -r minecraft

Screen is great for quick setups but lacks automatic restart on crash. For that, see the auto-restart guide.

Running in the Background with tmux

tmux is the modern alternative to screen with better pane splitting and scripting support:

sudo apt install tmux -y
tmux new-session -s minecraft
cd ~/minecraft-server
java -Xms2G -Xmx4G -jar server.jar --nogui

Detach with Ctrl+B then D. Reattach with:

tmux attach -t minecraft

Both screen and tmux let you send commands to the server console from outside the session, which is useful for scheduled tasks:

# Send a save-all command via tmux
tmux send-keys -t minecraft "save-all" Enter

# Send a say command via screen
screen -S minecraft -X stuff "say Server restarting in 5 minutes$(printf '\r')"

Running with systemd (Recommended for Production)

For a minecraft server headless linux setup that starts on boot, restarts on crash, and integrates with system logging, systemd is the gold standard. Create a service file:

sudo nano /etc/systemd/system/minecraft.service

[Unit]
Description=Minecraft Server
After=network.target

[Service]
User=minecraft
WorkingDirectory=/home/minecraft/server
ExecStart=/usr/bin/java -Xms2G -Xmx4G -jar server.jar --nogui
ExecStop=/usr/bin/screen -S mc-console -X stuff "stop$(printf '\r')"
Restart=on-failure
RestartSec=10
StandardInput=null
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable minecraft.service
sudo systemctl start minecraft.service

Check logs with journalctl -u minecraft -f. This approach pairs perfectly with the techniques described in the auto-restart guide.

Firewall Configuration

Open port 25565 (or your custom port) so players can connect:

# UFW (Ubuntu/Debian)
sudo ufw allow 25565/tcp

# firewalld (Rocky/Fedora)
sudo firewall-cmd --permanent --add-port=25565/tcp
sudo firewall-cmd --reload

Optimizing JVM Flags for Headless Servers

Running headless on Linux means you can squeeze extra performance from your JVM. See our best JVM flags for 2026 guide for the complete breakdown, but here is a solid starting point using Aikar's flags adapted for modern Java 21:

java -Xms4G -Xmx4G \
  -XX:+UseG1GC -XX:+ParallelRefProcEnabled \
  -XX:MaxGCPauseMillis=200 -XX:+UnlockExperimentalVMOptions \
  -XX:+DisableExplicitGC -XX:+AlwaysPreTouch \
  -XX:G1NewSizePercent=30 -XX:G1MaxNewSizePercent=40 \
  -XX:G1HeapRegionSize=8M -XX:G1ReservePercent=20 \
  -XX:G1MixedGCCountTarget=4 \
  -XX:InitiatingHeapOccupancyPercent=15 \
  -XX:G1MixedGCLiveThresholdPercent=90 \
  -XX:G1RSetUpdatingPauseTimePercent=5 \
  -XX:SurvivorRatio=32 -XX:+PerfDisableSharedMem \
  -XX:MaxTenuringThreshold=1 \
  -jar server.jar --nogui

Summary

Running a minecraft server headless linux setup is straightforward once you understand the three main approaches: screen for quick testing, tmux for interactive management, and systemd for production deployments. Whichever method you choose, always use the --nogui flag, set up proper backups, and configure your firewall. For the most reliable experience, combine systemd with the auto-restart techniques covered in our dedicated restart guide.

Want managed hosting instead? Astroworld Hosting handles auto-restarts, updates, and backups for you.