Docs · Project Zomboid

Install mods on a PZ server

Steam Workshop mods are what keep a Project Zomboid server alive months into a run — new weapons, vehicles, maps and quality-of-life fixes. But on a dedicated server, mods don’t “just work” the way they do in single-player, and Build 42 added a syntax change that silently loads zero mods if you miss it. This guide covers how server mods actually work, the B42 trap, and how to add and update mods without breaking your world.

How Workshop mods work on a server

A single Workshop mod is described by two different values, and a server needs both. The first is the Workshop ID — the long numeric ID from the Steam Workshop URL (for example 2392709985). It tells the server which item to download. The second is the Mod ID — a short text name the mod author defines internally (for example Brita). It tells the game which mod to actually enable.

On the dedicated server those go into two lines of the server .ini: WorkshopItems= takes the numeric IDs (what to fetch), and Mods= takes the Mod IDs (what to load), each list semicolon-separated. Get either list wrong and the mod is downloaded but never loads, or fails to download at all. This split is the source of most “my mods aren’t showing up” confusion.

The #1 Build 42 failure: the missing backslash

Build 42 quietly changed the Mods= syntax. Every Mod ID now needs a leading backslash. The B41 form that worked for years no longer does:

# B41 — worked for years, loads NOTHING on B42
Mods=Brita;BritaArmor;Tsarslib

# B42 — required form, backslash before every ID
Mods=\Brita;\BritaArmor;\Tsarslib

The cruel part: writing the bare B41 form on a B42 server produces no error. The server boots cleanly, players connect, and every mod simply fails to load. If you’ve upgraded a B41 server to B42 and your whole mod list vanished, this is almost always why. The numeric WorkshopItems= line is unaffected — only Mods= changed.

Adding mods on Forgehold

Open your server’s Mods tab. There are two ways to add a mod, and both resolve the Workshop ID and Mod ID for you so you never edit an .ini by hand.

Curated mods. The tab lists a vetted set of popular mods grouped by category — Essentials, Quality of Life, Interface, Weapons, Vehicles, Characters and Maps — each with a one-click Add button. Every entry carries a compatibility badge (B41, B42, or both) read from the mod’s own Steam tags. On a B42 server, mods that only declare B41 support are dimmed as an honest warning: many Workshop mods were built for Build 41 and may not load or may break a B42 save. The badges are best-effort signals, not a guarantee.

Paste a Workshop ID. For anything not in the curated list, paste a Steam Workshop URL or the numeric ID into the box and hit Add mod. If the mod declares dependencies — a common source of “why won’t this load” — a Dependencies detected dialog lists every required mod with its download size and offers to add them all in one click. Missing a dependency is one of the quietest ways to break a mod; resolving them up front avoids it.

Pinned mods appear in an ordered list you can drag to reorder. Load order matters in Zomboid — mods that patch each other generally need to load after what they depend on.

Why mod updates break servers — and the canary fix

Adding a mod is the easy part. The dangerous moment is updates. Workshop authors push new versions on their own schedule, and any of them can change a mod’s footprint, break against the current build, or fail to download cleanly. A previously-healthy server can be knocked over by an update to a single mod you didn’t even realise had changed — and you usually find out when players can’t connect.

Forgehold handles this with a staged canary preview. When updates are available, the Mods tab shows a count and a Preview update button. Clicking it spins up an isolated canary container — a throwaway copy that downloads and validates the new mod set completely off to the side, never touching your live world. It takes two to four minutes.

When the canary finishes, a preview opens showing each mod’s old version → new version, its download size and time, and a clear OK or Failed per mod. If anything failed to download cleanly, Promote is disabled — you can’t push a broken set to players. When every mod is green, one click promotes the update to the live server. If you don’t like what you see, reject it and nothing changes.

Every promotion is recorded, so if an update turns out to cause problems in-game that the canary couldn’t catch, you can roll back to the previous mod set in one click. The rollback takes an automatic safety snapshot first and restarts the server; your sandbox world data is untouched.

Restart behaviour and boot times

Any change to your mod list or config — adding a mod, promoting an update, reordering — takes effect on the next restart, because the server rebuilds its container to pick up the new configuration rather than hot-patching a running process. That keeps the running and the intended state honestly in sync.

Expect the first boot to take three to five minutes while Steam downloads Project Zomboid and any new mods for the first time. After that, warm restarts — where the game and mods are already cached on the host — come back in under 30 seconds. A big first-time modpack download is the slow case; day-to-day restarts are quick.