How to Add Workshop Mods and Maps to an Unturned Server
Unturned servers download Steam Workshop content themselves. You list the item IDs in WorkshopDownloadConfig.json, restart, and the server installs and updates them and their dependencies. For a custom map you then point the Map command in Commands.dat at the map's folder name. Players do not need to pre-install anything; they download the content automatically when they join.
Checked against the Unturned 3.x documentation on 2026-11-01. The Workshop is for assets (items, maps, vehicles and so on). Code plugins such as Rocket and OpenMod are a separate topic, covered in the plugin guide.
- Add Workshop item IDs to the
File_IDslist inWorkshopDownloadConfig.jsonand restart the server. - The ID is the number after
id=in the item's Workshop URL. - For a map, also set
Map FolderNameinCommands.dat. The folder name can differ from the Workshop title. - Players download server content automatically when they join; the server also monitors for Workshop updates and restarts on a timer.
- If a download or map fails, check the ID, the map name, and the startup console log first.
On this page
How to add a Workshop mod to an Unturned server
- Find the Workshop ID
Open the item on the Steam Workshop. The ID is the number in the URL after
id=, for example1753134636for the Hawaii map. - Add it to File_IDs
Open
WorkshopDownloadConfig.jsonin your server folder and add the number to theFile_IDslist. Separate several IDs with commas.{ "File_IDs": [1753134636, 2876376295] } - Restart the server
On startup the server installs and updates each listed item and the items it depends on. Large downloads can take a while, so watch the console.
- Confirm it loaded
Check the console for download errors. Maps need one more step (below); other content is simply available to the game once installed.
WorkshopDownloadConfig.json settings explained
A full file looks like this. Only File_IDs is something most servers ever change:
{
"File_IDs": [],
"Ignore_Children_File_IDs": [],
"Query_Cache_Max_Age_Seconds": 600,
"Max_Query_Retries": 2,
"Use_Cached_Downloads": true,
"Should_Monitor_Updates": true,
"Shutdown_Update_Detected_Timer": 600,
"Shutdown_Update_Detected_Message": "Workshop file update detected, shutdown in: {0}",
"Shutdown_Kick_Message": "Shutdown for Workshop file update."
}| Key | Meaning |
|---|---|
File_IDs | Workshop IDs of the mods and maps to download |
Ignore_Children_File_IDs | IDs from File_IDs whose required dependency items should not be downloaded |
Query_Cache_Max_Age_Seconds | How long Workshop query results are cached before refreshing; 0 forces an update check |
Max_Query_Retries | Retries for a failed download; best left alone |
Use_Cached_Downloads | Reuse cached downloads so restarts are faster on servers with many mods |
Should_Monitor_Updates | Watch for Workshop updates; when one lands, warn players and shut down after the timer |
Shutdown_Update_Detected_Timer | Seconds to wait before shutting down after an update is detected |
The Hawaii map is a good example of why Ignore_Children_File_IDs exists: the map requires a separate Hawaii Assets item, and listing the map ID in both lists downloads the map without that dependency. Leave dependencies on unless you know you do not need them.
How to load a Workshop map on your Unturned server
- Add the map's Workshop ID to
File_IDsand restart, so the server downloads it. - Find the map's real folder name. Look in the Workshop description, or open
Workshop/Steam/content/304930/inside your server folder, find the folder matching the Workshop ID, and open it. The folder next toMap.metais the map name. - Set it in
Commands.datwithMap FolderName(replace the existingMapline). - Restart again. The server loads the map on startup.
Maps also carry a version number. The server list uses it to check compatibility before players connect, which is why a map update that lands while players are online triggers the shutdown timer described below.
Do players need to install the mods?
Not manually. Per the official hosting documentation, players download the server's Workshop content automatically when they join. Players can also subscribe to items themselves on the Workshop, and subscribed content loads the next time they launch the game, but a server's required content comes down on connect either way.
Plan for the first join: a player connecting to a server with several large maps or mods waits for those downloads, and slow connections are where timeouts show up. Mention your Workshop list in your server description or Discord so players are not surprised.
Keeping Workshop content updated
With Should_Monitor_Updates on (the default in the documented file), the server notices when a creator updates a listed item, warns players in chat, and shuts down after Shutdown_Update_Detected_Timer seconds. That is a shutdown, not a restart: something has to start the server again so it can download the new version. A hosting panel's restart handling or a loop script does this.
Game updates are separate. The Enable_Update_Shutdown and scheduled shutdown options in Config.txt handle Unturned updates and the roughly daily restart the official docs recommend. Together they give you a server that heals itself overnight.
Unturned Workshop troubleshooting
| Symptom | Check this first |
|---|---|
| Server starts but the map never loads | Confirm the map ID is in File_IDs, you restarted after adding it, and Map in Commands.dat matches the folder name exactly |
| Item missing after restart | Look for a download error in the startup log; confirm the ID is the number after id= and the item is not private or removed |
| Map loads but looks broken | A dependency may be missing, for example if the map ID is also in Ignore_Children_File_IDs |
| Players time out while joining | Large downloads on slow connections. The Server section of Config.txt has Timeout_Queue_Seconds (documented default 15); some admins raise it, as Unturned's developer suggested for one Workshop-map issue |
| Server shuts down unexpectedly | A Workshop update was detected and the shutdown timer ran out; check the log for the update message |
| Mod stopped working after a game update | The item may need an update from its author; check its Workshop page for the latest change note |
When asking for help, include the startup console output and the contents of WorkshopDownloadConfig.json. Those two things answer most questions.
Frequently asked questions
Where do I put the Workshop ID on an Unturned server?
In the File_IDs list in WorkshopDownloadConfig.json, then restart. The ID is the number after id= in the Workshop item's URL.
Do my players need to subscribe to the server's mods?
No. Unturned downloads the server's Workshop content automatically when players join, though first joins can be slow if the content is large.
Why does my Workshop map not load?
Usually the Map command does not match the map's folder name, or the server was not restarted after the ID was added. The folder name can differ from the Workshop title.
Why does my server shut down by itself after a mod update?
Should_Monitor_Updates is on, so the server warns players and shuts down after a timer when a listed Workshop item updates. Something needs to start it again to download the new version.