Skip to content

Project Zomboid Mods: How to Install Workshop Mods on a Server (Build 42)

Install Steam Workshop mods on a Project Zomboid server: WorkshopItems and Mods IDs, map mods, Build 42 vs 41, and fixes when a mod won't load.

Updated October 28, 2026
Project Zomboid

Project Zomboid mods come from the Steam Workshop, and a server needs two lines in its settings file to use them: one that downloads each mod and one that enables it. The server fetches the Workshop items itself every time it starts, and players are prompted to install the same items when they join. This guide covers installing mods on your Project Zomboid server step by step, on Build 42. For first boot and connecting, see Project Zomboid Dedicated Server: Setup, Ports, RAM and Updates (Build 42).

The two lines live in your server's .ini:

WorkshopItems=2313387159;2544353492;2840889213
Mods=BetterSortCC;P4HasBeenRead;Chestown
ini

That example is three real Workshop items whose pages say they work on Build 42: Better Sorting, Has Been Read and the Chestown map.

Each Workshop item has a:

  • Workshop ID (a number, used in WorkshopItems)
  • Mod ID (text, used in Mods)

Both are listed on the mod's Workshop page, under "Workshop ID" and "Mod ID".

How to Install Mods on Your Server

  1. Collect the IDs. Open each mod's Steam Workshop page. The Workshop ID is the number at the end of the page URL (?id=2313387159) and is usually repeated in the description. The Mod ID is listed in the description as Mod ID:. It's the id= line in the mod's own mod.info file.
  2. Stop the server from the Console tab.
  3. Open the settings file. In the File Manager, go to .cache/Server/ and open the .ini named after your Server Name on the Startup tab: Pterodactyl.ini if you never changed it. Project Zomboid Server Settings and Config Files explains the four files in that folder.
  4. Add the IDs. Put every Workshop ID on the WorkshopItems= line and every Mod ID on the Mods= line, separated by semicolons, with no spaces around them. A Mod ID can contain spaces of its own (Authentic Z - Current is one), so copy it exactly.
  5. Start the server with the Console tab open. It shows "Downloading workshop items" and a "Downloaded N of N" count, then loads the mod list.
  6. Join. Your players see "The server you are joining requires these Steam Workshop items:" and can install them from that screen.

Mods are read when the server starts, so a mod change always needs a restart. /reloadoptions re-reads other .ini settings while the server runs, but it doesn't download or load a new mod.

You don't need to upload mod files

The game's own server settings screen says it plainly: "The server will install Workshop items when starting. Clients will be prompted to install Workshop items when joining the server." The server logs in to Steam anonymously for this, so it needs no Steam account. The Steam Auto Update variable on the Startup tab only updates the game itself. Workshop items are checked at every start either way.

When a Mod Does Not Load

Start with the two IDs, because they are not interchangeable:

  • WorkshopItems= is the download list and takes the numeric Workshop ID. The server fetches those items from Steam.
  • Mods= is the enable list and takes the text Mod ID out of the mod's mod.info. The server only loads what is named here. This is the line that turns a mod on.

Put a number in Mods= and the mod downloads but is never enabled. Put a name in WorkshopItems= and nothing downloads at all: the server skips any entry that isn't a valid numeric ID, without an error. Both fields are semicolon-separated.

Then work down this list:

  • One Workshop item can contain several mods. Its page lists Mod ID: more than once. Authentic Z (Workshop item 2335368829), for example, publishes Authentic Z - Current, AuthenticZLite and AuthenticZBackpacks+. Read the description before you paste: sometimes those are alternatives and you pick one, sometimes they are all required. Anything left out of Mods= is not loaded.
  • Dependencies need their own two entries. A mod that needs another mod lists it under Required Items on its Workshop page (and in require= in its mod.info). The dependency needs its own Workshop ID and its own Mod ID in your config. It doesn't come along on its own.
  • Check the build. Mods are build-specific, and a mod written for Build 41 won't necessarily load on Build 42. See the next section.
  • Read the boot output. Start the server with the Console tab open and watch it load the mod list. The same output is written to .cache/server-console.txt, which you can open in the File Manager after the fact.
  • The server stopped during "Downloading workshop items". If a Workshop download fails, the server stops instead of starting without the mod. Check the Workshop ID on that line, and whether the item is still public on Steam.

A backslash in front of each Mod ID is fine

Build 42 lists often look like Mods=\ModA;\ModB. The server strips every \ from the Mods= line before it splits it, so \ModA and ModA load the same mod. You don't need to add or remove them.

Map Mods Need a Third Line

A map mod is the one type the two fields above do not cover on their own. Map= decides which map folders the world is built from, and it defaults to Map=Muldraugh, KY. A map mod listed in WorkshopItems= and Mods= but not in Map= will download and load, and its map will never be part of the world.

The value is the map folder name, which map mods publish on their Workshop page alongside the other two IDs. Chestown, the third Workshop item in the example at the top of this page, lists Mod ID: Chestown and Map Folder: Chestown, KY. With Workshop ID 2840889213, that makes its three lines:

WorkshopItems=2840889213
Mods=Chestown
Map=Chestown, KY;Muldraugh, KY
ini

Put the mod's folder before Muldraugh, KY. That is the order the game's own server settings screen writes when you add a map mod: new map folders go on top of the list, the vanilla map stays at the bottom.

If the map ships its own spawn points, add it to <servername>_spawnregions.lua in .cache/Server/ as well, or players will never be offered a spawn on it.

Build 42 or Build 41 Mods?

Your server and every player have to run the same game branch, and each mod has to support it. Our servers install the default branch, which is Build 42.

  • Read the Workshop page, not just the tags. Authors say which build a mod supports in the title or description: Has Been Read says "Confirmed to work with Build 41 and Build 42 Stable, including multiplayer". The Build 41 and Build 42 tags alone aren't proof. Some mods are tagged for both and say in their title that they're Build 41 only.
  • A mod can declare its own limits. mod.info supports versionMin= and versionMax=, which tell the game which versions it works on.
  • Running a Build 41 mod list? Set Steam Beta Branch on the Startup tab to legacy41 and reinstall (back up first). Every player then picks the same branch in Steam. Project Zomboid Multiplayer: How to Play With Friends explains matching branches.

Don't mix the two. A mod that only supports Build 41 can download fine on a Build 42 server and still fail to load.

Can I Add Mods to an Existing Save?

Yes. Add the IDs to WorkshopItems= and Mods=, restart, and the world, the characters and everything built in it carry on. Back the save up first.

Removing a mod is the direction that hurts. A world that has already spawned a mod's items, vehicles or tiles can fail to load once the mod that defines them is gone, and a save that won't load is usually not recoverable. Restore the backup.

Map mods are worth holding for a wipe, and their authors often say so outright: the Build 41 map Raven Creek's page tells you to start a new game after every update to it.

Important

Test a new mod list on a fresh save first. Some mods are incompatible with existing characters or with each other, and it's better to find that out before your group's main world depends on it.

When a Mod Updates

Players' Steam clients download a mod update right away. The server only fetches Workshop items when it starts, so until you restart it, players who have the new version are refused with "File doesn't match the one on the server". Restart the server after a mod you use updates. Project Zomboid "File doesn't match the one on the server" explains reading the file path in that error.

FAQ

Does Project Zomboid automatically download mods?

On a server, yes. The server downloads everything in WorkshopItems= each time it starts, and players joining get a "requires these Steam Workshop items" screen to install the same items. Players don't have to subscribe to everything in advance.

Where do I put mods on a Project Zomboid server?

You don't upload mod files. You list them in .cache/Server/<servername>.ini: Workshop IDs on WorkshopItems=, Mod IDs on Mods=. The server fetches them from the Workshop on its next start.

Can I add mods mid-game?

Yes. Add both IDs and restart. Existing worlds keep going with the new mod. Removing a mod from a world that uses it is the risky direction, so back up first.

Why is my mod downloaded but not working?

Its Mod ID isn't on the Mods= line, or a numeric Workshop ID was put there by mistake. Also check that it's a Build 42 mod and that its required items are listed too.


Made with 💜 by GameServerKings

Need a Project Zomboid server?

Deploy an instantly-provisioned Project Zomboid server on high-clock hardware. DDoS protected, no contracts, cancel anytime.

From $12.00 /month