Project-Zomboid-Ubuntu-Server

Project Zomboid Dedicated Server on Ubuntu — Complete Setup Guide

Step-by-step guide to install, configure, and run a Project Zomboid dedicated server on Ubuntu 22.04 / 24.04 LTS using SteamCMD. Covers firewall setup, RAM configuration, mod installation, server recovery, and common troubleshooting. Works on any VPS provider (Hostinger, DigitalOcean, Hetzner, Vultr, AWS, Linode, etc.).

🇧🇷 Versão em Português

Why this guide?
Prerequisites
Installation
Configuration
Running the Server
Installing Mods
Server Management
Troubleshooting
FAQ
Acknowledgements
License

Why this guide?

Most tutorials for hosting a Project Zomboid server on Linux skip important details like RAM allocation, firewall rules, or mod management. This guide was built from real experience hosting private servers and covers:

✅ Full installation from scratch on a fresh Ubuntu VPS
✅ Firewall (UFW) configuration to avoid connection issues
✅ SteamCMD setup and anonymous login
✅ RAM tuning via ProjectZomboid64.json
✅ Importing server settings from a local Windows machine
✅ Running the server in the background with screen
✅ Installing workshop mods via SCP or SFTP (FileZilla)
✅ Common errors and how to fix them

Prerequisites

Before you begin, make sure you have:

A VPS or dedicated machine running Ubuntu 22.04 or 24.04 LTS (64-bit) — other Debian-based distros likely work too
At least 4 GB RAM (8 GB recommended for a stable experience with mods)
sudo privileges on the server
Basic knowledge of terminal / Linux commands
Project Zomboid purchased on Steam (required for mod access — the server itself is free)
An SSH client (e.g., PuTTY on Windows, built-in terminal on macOS/Linux)

Installation

1. Update the system and configure the firewall

sudo apt-get update && sudo apt-get upgrade -y

Enable UFW (firewall):

sudo ufw enable

⚠️ Important: If you are connected via SSH, allow your SSH port before enabling the firewall, otherwise you will lose access:

sudo ufw allow 22        # SSH (default port — change if you use a custom port)

Allow the Project Zomboid server ports:

sudo ufw allow 16261/udp  # Main game port (UDP)
sudo ufw allow 16262/udp  # Direct connection port (UDP)
sudo ufw reload

Verify the rules are active:

sudo ufw status

You should see 16261 and 16262 listed as ALLOW.

2. Create a dedicated user for Steam

It is best practice to run game servers under a separate non-root user:

sudo adduser steam
sudo usermod -aG sudo steam
sudo chown steam:steam /home/steam/ -R
sudo chmod -R 755 /home/steam/

3. Enable 32-bit architecture support and install SteamCMD

Switch to the steam user’s directory:

cd /home/steam

Enable the multiverse repository and 32-bit support (required by SteamCMD):

sudo add-apt-repository multiverse
sudo dpkg --add-architecture i386
sudo apt update
sudo apt install steamcmd -y

4. Download the Project Zomboid Dedicated Server

Switch to the steam user:

su - steam
cd ~
steamcmd

Inside SteamCMD, run these commands:

force_install_dir /home/steam/pzsteam
login anonymous
app_update 380870 validate
exit

380870 is the Steam App ID for the Project Zomboid Dedicated Server. It is free and can be downloaded without owning the game.

Configuration

1. Set the RAM allocation

Navigate to the server directory:

cd /home/steam/pzsteam

Edit the JVM configuration file:

nano ProjectZomboid64.json

Find the -Xmx parameter and set it to the amount of RAM you want to dedicate:

-Xmx4g → 4 GB RAM
-Xmx8g → 8 GB RAM (recommended for most servers)
-Xmx16g → 16 GB RAM (for large modpacks or many players)

RAM configuration example

2. Import server settings from your local machine (optional but recommended)

The easiest way to configure game settings (map, loot, difficulty, sandbox) is to:

Open Project Zomboid on your local Windows PC
Create and configure a server through the in-game “Host” menu
Navigate to the settings folder on Windows:
```
C:\Users\<YourUsername>\Zomboid\Server\
```
Copy these three files:
- <servername>.ini
- <servername>_SandboxVars.lua
- <servername>_spawnregions.lua

Upload them to your Linux server at:

/home/steam/Zomboid/Server/

Using SCP:

scp C:\Users\<YourUsername>\Zomboid\Server\<servername>* steam@<your-vps-ip>:/home/steam/Zomboid/Server/

Or use a GUI tool like FileZilla (connect via SFTP on port 22).

Running the Server

1. Start a persistent screen session

screen keeps the server running after you disconnect from SSH:

screen -S zomboid

2. Start the server

cd /home/steam/pzsteam
./start-server.sh -servername <yourservername>

Replace <yourservername> with the name of your .ini config file (without the .ini extension).

3. Detach from screen (keep server running in background)

Press Ctrl + A, then D.

4. Re-attach to check the server console

screen -r zomboid

5. Stop the server gracefully

Re-attach with screen -r zomboid, then type:

quit

Wait for the world save to complete before closing the session.

Installing Mods

Method 1: Upload mod files via SCP / SFTP

Download mods from the Steam Workshop on your local PC
Locate the downloaded mod folder on Windows:
```
C:\Users\<YourUsername>\Zomboid\mods\
```

Upload the mod folder to your VPS:

scp -r "C:\Users\<YourUsername>\Zomboid\mods\<ModName>" steam@<your-vps-ip>:/home/steam/Zomboid/mods/

Or use FileZilla via SFTP.

Add the mod IDs to your server .ini file:

Mods=<ModID>;<AnotherModID>
WorkshopItems=<WorkshopID>;<AnotherWorkshopID>

Mod IDs and Workshop IDs are found on the mod’s Steam Workshop page URL and inside the mod’s mod.info file.

Method 2: Download Workshop mods via SteamCMD

Inside SteamCMD (logged in as anonymous):

workshop_download_item 108600 <WorkshopID>

Mods download to /home/steam/.steam/steamapps/workshop/content/108600/<WorkshopID>/.
Copy or symlink them to /home/steam/Zomboid/mods/.

Server Management

Check if the server is running

screen -ls

Update the server to the latest version

steamcmd
login anonymous
app_update 380870 validate
exit

Then restart the server.

View server logs

ls -lt /home/steam/Zomboid/Logs/     # find the latest log file
cat /home/steam/Zomboid/Logs/<latest>.txt | tail -100

Backup your server world

cp -r /home/steam/Zomboid/Saves/ /home/steam/Zomboid/Saves_backup_$(date +%Y%m%d)/

Troubleshooting

❌ “Connection failed” / Cannot connect to the server

Check ports are open: sudo ufw status — look for 16261 and 16262
Confirm the server is running: screen -ls
Check your VPS provider’s cloud firewall / security group — many providers have a separate firewall that also needs UDP 16261–16262 opened
Verify your server IP: curl ifconfig.me

❌ Server crashes on startup

Check available RAM: free -h — reduce -Xmx in ProjectZomboid64.json if needed
Read the latest log: ls -lt /home/steam/Zomboid/Logs/ then cat the most recent file
Validate server files: re-run app_update 380870 validate in SteamCMD

❌ “Failed to set thread priority” warning

This is a harmless warning on most Linux VPS environments. The server runs normally.

❌ Mods not loading

Confirm both Mods= and WorkshopItems= are set correctly in the .ini file
Verify the mod folder exists at /home/steam/Zomboid/mods/<ModID>/
Restart the server after any mod changes

❌ SteamCMD error: `0x202` or `0x212`

Steam network timeout. Wait a few minutes and retry. If persistent:

rm -rf /home/steam/.steam/steamcmd/appcache
steamcmd +login anonymous +app_update 380870 +quit

❌ `su - steam` asks for a password you don’t know

Reset it:

sudo passwd steam

❌ Port 16261 is open in UFW but players still can’t connect

Your VPS provider likely has a separate cloud-level firewall (Hostinger hPanel, DigitalOcean Firewall, AWS Security Groups). Log into your provider dashboard and add UDP rules for ports 16261 and 16262 there too.

FAQ

Q: Does running the server require owning Project Zomboid on Steam?
A: No. The dedicated server (App ID 380870) is free and downloads anonymously via SteamCMD. Only the players connecting need to own the game.

Q: How many players can the server support?
A: Officially up to 32 players. With 8 GB RAM and a modern CPU, 8–16 simultaneous players is very comfortable.

Q: Which Ubuntu version should I use?
A: Ubuntu 22.04 LTS or 24.04 LTS. Avoid non-LTS releases for production servers.

Q: Can I run this on a Raspberry Pi or ARM machine?
A: No. The Project Zomboid dedicated server is x86-64 only — ARM is not supported.

Q: My server IP keeps changing. How do I get a static IP?
A: All major VPS providers give you a static public IP by default. If hosting at home, use a DDNS (Dynamic DNS) service.

Q: How do I set a server admin password?
A: The server prompts you on first startup. To reset it later, edit <servername>.ini and update the AdminPassword= field.

Q: Can I run the server without screen, using systemd instead?
A: Yes — you can create a systemd service to auto-start the server on boot. Open an issue if you’d like a ready-made template added to this repo.

Q: What VPS provider is recommended?
A: Hetzner (Europe/US) and Vultr offer great price/performance. Hostinger is budget-friendly. DigitalOcean has excellent documentation. Choose the datacenter closest to your players for lowest ping.

Q: The server starts but nobody can join — what should I check first?
A: In order: (1) Cloud firewall in your VPS provider dashboard, (2) UFW rules with sudo ufw status, (3) correct IP address, (4) server console for errors via screen -r zomboid.

Acknowledgements

Project Zomboid Wiki — Dedicated Server — official documentation
Valve SteamCMD Documentation — SteamCMD reference
r/projectzomboid — community tips and feedback
Everyone who opened issues and contributed improvements to this repository ❤️

💖 Support this project

If this guide saved you time, consider giving the repo a ⭐ — it helps others find it!

Contact & Contributing

Found a bug in the guide or have a tip to add?
👉 Open an issue — all feedback is welcome.

Pull requests are also welcome. See CONTRIBUTING.md for guidelines.

License

This project is open-source under the MIT License.

This site is open source. Improve this page.