Project Zomboid mods are unusual, and it catches almost everyone out the first time. Every Workshop item has two completely different identifiers, both of which have to end up in your server’s config, in different places, in a specific order. Get one wrong and the server starts perfectly and simply behaves as though the mod does not exist. Add a map mod and there is a further rule about ordering that, if broken, produces a server where players spawn into empty space. This guide explains how Project Zomboid actually loads mods, what those two IDs are, the map ordering rule, and how to add mods and maps on a Loafhosts server without hand-editing anything.
How Project Zomboid Loads Mods
Project Zomboid does not need a separate download step. The dedicated server reads its list of Workshop items from the server INI at startup and downloads whatever is missing, in place. That is why adding a mod needs a restart rather than a reinstall, and why nothing is wiped in the process.
Three keys in the INI do the work:
| Key | What it holds |
|---|---|
WorkshopItems= | The numeric Workshop IDs the server should download |
Mods= | The text mod IDs, which are the actual folder names the game loads |
Map= | The map names, for map mods only |
Note: Adding mods needs a restart, not a reinstall. Nothing is wiped and your save is untouched
Note: The server downloads Workshop items itself at boot, so there is no separate download step to run
The Two IDs Problem
This is the single biggest source of “my mod is installed but does nothing”.
The numeric ID is the one in the Workshop URL, for example 2200148440. That goes in WorkshopItems=. The text ID is the mod’s internal folder name, something like Brita_2, and that goes in Mods=. They are not the same thing and one does not imply the other.
If you put the number in both places, the server downloads the mod correctly and then fails to load it, because there is no folder by that name. Nothing errors loudly. The mod is just absent.
To make it more interesting, a single Workshop item can contain several text mod IDs. Large mods often ship as a bundle, so one number can require three or four entries in Mods=.
| What you have | Where it goes | Example |
|---|---|---|
| Number from the Workshop URL | WorkshopItems= | 2200148440 |
| Text mod ID from the mod page | Mods= | Brita_2 |
| Map name, map mods only | Map= | Rosewood Expansion |
Warning: Putting the numeric ID in
Mods=is the most common Project Zomboid modding mistake. The server downloads the mod and then never loads itTip: A mod page usually lists its Mod ID separately from the Workshop ID. If it lists several, all of them go in
Mods=
The Map Order Rule That Breaks Servers
Map mods add entries to Map=, and the order of that list is not cosmetic. The base map entry, Muldraugh, KY, must be the last entry in the list.
Project Zomboid resolves the map list in order, with later entries acting as the fallback for anything earlier entries do not define. Put the base map first and it answers for everything, so your custom maps never get a chance to load. The symptom is a server that starts fine and drops players into the wrong place or into nothing at all.
Map=Rosewood Expansion;Custom Map Name;Muldraugh, KY
On a Loafhosts server this is enforced for you. The Mod Manager applies the ordering rule when it writes the INI, so a correct list is produced even if you added the maps in a different order.
Warning:
Muldraugh, KYmust be the final entry inMap=. Any other order can leave players spawning into empty terrainTip: If players load into a void after you add a map mod, check the map order before anything else
Adding Mods in the Panel
Open your server in the LoafHub panel and pick Mod Manager from the sidebar. You can browse the Steam Workshop from inside the panel, so there is no copying IDs between browser tabs.
- Open your server and go to Mod Manager
- Search the Workshop, or paste a Workshop URL or ID
- Add the mods and maps you want
- Apply, which writes the INI and restarts the server
- Wait for the restart, the server downloads anything new during boot
The panel resolves both IDs for you. It reads the Workshop page to work out the text mod IDs behind a numeric one, and after a first apply it confirms them against the folders actually on disk. That is the step people do by hand and get wrong.
Collections work the same way, so a curated collection can be added in one action rather than item by item.
Tip: The first boot after adding a large mod or map is slow, because the server is downloading. Give it time before assuming it has hung
Note: The panel resolves the text mod IDs for you, including when one Workshop item contains several
A Brand New Server Has No Config Yet
Project Zomboid does not write its server files until a world has been created. On a server that has never been started, there is no INI to edit and no sandbox file to change, which is why a config editor can look empty on a fresh deployment.
The fix is simply to start the server once and let it generate the world. On Loafhosts, the config tools offer a bootstrap action that seeds the files so you can configure the server before its first real boot.
Note: A new Project Zomboid server has no INI until the world exists. An empty config screen on a fresh server is normal
Tip: Configure the sandbox before your players start, some world settings are much more disruptive to change later
Removing a Mod Safely
Removing mods is riskier than adding them, because a world can contain items, vehicles, or map tiles that only that mod defines.
- Item and vehicle mods are usually survivable. Items the game no longer recognises disappear from the world.
- Map mods are not. If players built or stored things in a modded map area, removing the mod removes the area.
- Framework mods that other mods depend on will break everything that relies on them.
Take a backup before removing anything, and check whether other mods in your list depend on it.
Warning: Removing a map mod can permanently remove any part of the world it provided, including player bases built there
Tip: Back up before removing a mod. It is the only way to reverse a decision that turns out badly
Why Your Mod Still Is Not Loading
| Symptom | Usual cause |
|---|---|
| Mod downloads but has no effect | Numeric ID used in Mods= instead of the text mod ID |
| Only part of a large mod works | The item contains several mod IDs and not all were added |
| Players spawn into nothing | Muldraugh, KY is not the last entry in Map= |
| Nothing changed after applying | The server was not restarted, the INI is read at boot |
| Config screen is empty | The world has not been generated yet |
| Mod worked, then stopped after an update | The mod updated and now requires a dependency you do not have |
Tip: Change one mod at a time on a server people are playing on. A batch of ten makes finding the broken one much harder
Frequently Asked Questions
How do I install mods on a Project Zomboid server?
Open your server in the LoafHub panel, go to Mod Manager, search the Workshop or paste an ID, add what you want, and apply. The panel writes both the numeric Workshop ID and the text mod ID into the server INI and restarts. The server downloads the mods itself during boot.
Why is my Project Zomboid mod not working?
Almost always because the numeric Workshop ID was used where the text mod ID belongs. WorkshopItems= takes the number from the URL, Mods= takes the mod’s folder name. Also check whether that Workshop item contains several mod IDs, since all of them need to be listed.
How do I run multiple maps on a Project Zomboid server?
Add each map mod, then make sure the Map= list has your custom maps first and Muldraugh, KY last. The base map acts as the fallback and must come at the end, or the custom maps never load. The panel enforces this ordering when it writes the file.
Why do my players spawn into an empty world after adding a map?
The map order is wrong. If Muldraugh, KY is not the final entry in Map=, it resolves everything before your custom maps get a chance, and players end up somewhere that does not exist properly.
Do I need to reinstall my server to add mods?
No. Project Zomboid reads its mod list at startup and downloads what is missing in place, so a restart is enough. Nothing is wiped and your existing save is not affected.
Why is my Project Zomboid config editor empty?
The server has not generated its world yet, so the INI and sandbox files do not exist. Start the server once, or use the bootstrap action to seed the files, then configure it.
Is it safe to remove a Project Zomboid mod?
It depends on the mod. Item and vehicle mods are usually fine. Removing a map mod can delete the part of the world it added, along with anything players built there. Always back up first.