Guides / Mods
How to Add Steam Workshop Mods to a Project Zomboid Server
Mods are what keep Knox County interesting long after you have looted every warehouse in Muldraugh. The Steam Workshop hosts thousands of Project Zomboid mods - new maps, vehicles, weapons, professions, quality-of-life fixes - and a Build 41 dedicated server can run them all. This guide covers how to add Workshop mods with the Flux dashboard Mod Manager, why load order matters, how map mods differ, what the equivalent manual servertest.ini edit looks like, and how to fix the mods that stubbornly refuse to load.
The two IDs every Project Zomboid mod has
Almost every problem people hit with Project Zomboid server mods comes from one confusion, so it is worth clearing up before anything else. Every Workshop mod has two different identifiers:
- The Workshop ID - the long number at the end of the Steam Workshop URL (the
?id=part). It identifies the Workshop item the server must download. - The Mod ID - a short text name chosen by the mod author (something like
ExampleModName). It identifies the mod the game must load.
Your server config needs both, in two separate lines of servertest.ini. The WorkshopItems= line takes the numeric Workshop IDs, so the server knows what to download from Steam. The Mods= line takes the text Mod IDs, so the game knows what to actually enable. A single Workshop item can even contain several Mod IDs - that is why a mod can download perfectly and still do nothing in game.
The easy way: the dashboard Mod Manager
Every Project Zomboid server deployed on Flux ships with a Steam Workshop Mod Manager in the web dashboard, and it exists specifically to remove that two-IDs trap. You paste in a Steam Workshop link or just the numeric ID, and the Mod Manager resolves the Mod ID and the Workshop ID automatically, then writes both the WorkshopItems and the Mods lists in servertest.ini for you. No SSH, no file hunting, no copying strings out of a mod description.
- Open the mod on the Steam Workshop and copy the page URL from your browser (or just the numeric ID at the end of it).
- Open the Mod Manager in your Flux dashboard.
- Paste the link or ID and add it. The Mod ID and Workshop ID are resolved and both config lists are updated for you.
- Check the load order - drag dependencies and frameworks above the mods that rely on them.
- Add the map name to the
Map=line if you added a map mod (more on that below). - Restart the server. Workshop items download on the next couple of restarts, and once they are on disk the mods load.
Repeat for as many mods as you want. The rest of the dashboard - file manager, config editor, Source RCON console, backups - sits alongside it, so you can check a log or roll back a save without leaving the browser.
Why load order matters
Project Zomboid loads mods in the order they appear in the Mods= list, left to right, and later mods override earlier ones when two mods touch the same script, item or texture. That makes the order a real setting, not cosmetic. Three rules cover most cases:
- Dependencies and frameworks go first. If a mod says "requires X" in its Workshop description, X must appear earlier in the list. A dependency loaded after its dependant is the single most common reason a mod appears installed but does nothing.
- Patches and compatibility fixes go last. A patch that reconciles two mods has to load after both of them, or it has nothing to patch.
- Keep the order stable. Once a world has generated with a given order, shuffling maps or overhaul mods mid-save can corrupt chunks. Settle your mod list before you start a long run.
When two mods genuinely conflict - both replacing the same vanilla item - the one further down the list wins. If a mod is not behaving the way its Workshop page describes, moving it in the order is the first thing to try.
Mods need a restart (and often two)
Adding a mod does not take effect live. The server has to fetch the Workshop item from Steam, and that fetch happens as part of startup - which means mods download on the next couple of restarts, not instantly. It is completely normal for a freshly-added mod to be missing after the first restart and present after the second: the first boot queued and downloaded the files, the second boot actually loaded them. Give the server a moment, restart again, and check the log before assuming something is broken. Tell your players too, so nobody panics when the new map is not there yet.
Map mods are a special case
Map mods need one extra step that every other mod type does not. Adding the Workshop ID and Mod ID makes the server download and enable the mod, but Project Zomboid still will not use the new terrain unless the map is added to the Map= line in servertest.ini. That line is a semicolon-separated list of map folder names, and the vanilla map must stay at the end of it:
Map=MyCustomMap;Muldraugh, KY
The name you add is the map folder name, which the mod author normally states on the Workshop page - it is not necessarily the Mod ID and not necessarily the pretty name shown in game. Custom maps go before Muldraugh, KY, which represents the base game map and acts as the fallback for everything the custom maps do not cover. Stacking several map mods works, but overlapping maps will fight over the same cells - check each map's Workshop page for its coordinates before combining them. As with any map change, adding or removing a map mod on an existing world can leave odd seams where players have already explored, so it is best done on a fresh save.
Doing it manually: editing servertest.ini
It is worth knowing what the Mod Manager is doing under the hood, both for self-hosted servers and for troubleshooting. Open servertest.ini in the dashboard config editor (or via the file manager) and you will find three relevant lines:
WorkshopItems=2169435993;2392709985- semicolon-separated numeric Workshop IDs. This is the download list.Mods=ModIdOne;ModIdTwo- semicolon-separated text Mod IDs, in load order. This is the enable list.Map=MyCustomMap;Muldraugh, KY- semicolon-separated map folder names, only needed for map mods.
Every mod you want must appear in both the first and second lines. Save the file, restart the server, and the behaviour is identical to using the Mod Manager - you have just done the ID lookup by hand. Manual editing is exactly where the classic mistakes happen: pasting a Workshop ID into Mods=, forgetting one of the two lists, or leaving a stray semicolon at the end of the line.
Troubleshooting: mods that will not load
The mod is in the list but nothing changed
Check the Mods= line contains the Mod ID, not the numeric Workshop ID - a mismatched Mod ID is the number-one cause. The server log names each mod as it loads, so compare what the log says it loaded against what you expected. Also confirm the mod has actually finished downloading; if it has only been through one restart, restart again.
Players get kicked or see a mod mismatch on join
The server pushes its mod list to connecting clients, but clients still need the mod files themselves. Every player should subscribe to the same mods on the Steam Workshop and let Steam finish downloading before they connect. If one player is missing a mod - or has an old copy of it - they will be rejected while everyone else plays fine. See how to play multiplayer with friends for the full join flow.
Everything broke after a mod updated
Workshop mods update on the author's schedule, and a mid-session update produces a version mismatch: the client has the new files, the running server still has the old ones. The fix is to restart the server so it pulls the current version, and have players verify their Steam downloads have completed. Restarting the server after a wave of Workshop updates - and before a session - saves a lot of confusion. Take a backup first; the dashboard has backup and restore built in.
A dependency is missing
Many mods depend on a framework mod. If the Workshop page lists required items, add every one of them and place them earlier in the load order. The server log will usually complain about a missing script or table when a dependency is absent.
Give your mods somewhere to run
Mods are memory-hungry. A vanilla Build 41 world is happy inside the entry plan's 4 GB of RAM, 2 CPU cores and 15 GB of SSD, but a long mod list - especially with big custom maps - wants more headroom. Our plans start at 8 slots for $3.97/mo, with 16 slots at $5.36/mo and 32 slots at $7.49/mo (32 players is the cap), and every plan includes dedicated resources, DDoS protection, the Mod Manager and a choice of 50+ regions. See the server requirements for how specs map to player counts, or the setup guide if your server is not up yet. Prefer the whole picture on why the network is built this way? Read why we host on a decentralized cloud.
FAQ
How do I add Steam Workshop mods to a Project Zomboid server?
Open the Mod Manager in your Flux dashboard and paste the Steam Workshop link or the numeric Workshop ID. The Mod ID and Workshop ID are resolved automatically and written into both the WorkshopItems and Modslists in servertest.ini. Restart the server and the mods download over the next couple of restarts.
Why is my Project Zomboid mod not loading?
Most often a mismatched Mod ID (the Mods= list needs the Mod ID, not the Workshop ID), a mod that has not finished downloading, a missing dependency, or the wrong load order. Map mods also need their map name on the Map= line.
Do players need to subscribe to the mods too?
Yes. The server pushes its mod list to connecting clients, but each player still needs the files locally. Subscribe on the Steam Workshop, let Steam download, then join.
Does load order matter?
Yes. Mods load in list order and later mods override earlier ones, so dependencies and frameworks must come first and compatibility patches last.