How to Add Workshop Mods and Maps to an Unturned Server
Unturned servers download Steam Workshop content themselves. You list the item IDs (on the Mods tab, or in the Workshop mods config, which is WorkshopDownloadConfig.json), restart, and the server installs and updates them and their dependencies. For a custom map you then point the server 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 on the Mods tab, or to the
File_IDslist in Workshop mods on the Configs tab, then restart the server. - The ID is the number after
id=in the item's Workshop URL. - For a map, also set it on the Startup tab (Workshop map or Map). 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 shuts down on a timer when one lands, so it has to be started again.
- If a download or map fails, check the ID, the map name, and the Console tab output 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 the server
Open your server in the panel. Either use the Mods tab, or open Configs, Workshop mods and add the number to the
File_IDslist (separate several IDs with commas), then click Save.{ "File_IDs": [1753134636, 2876376295] } - Restart the server
Click Restart at the top of the page. 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 tab.
- Confirm it loaded
Check the Console tab 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 (Configs, Workshop mods). 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 (on the Mods tab or in
File_IDs) and click Restart, so the server downloads it. - Find the map's real folder name. Look in the Workshop description, or on the Files tab open
Workshop/Steam/content/304930/, find the folder matching the Workshop ID, and open it. The folder next toMap.metais the map name. - Open the Startup tab and set the map: use Workshop map for a Workshop map, or put the folder name in Map (the game's
Map FolderName). Click Save startup. - Click 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: the server has to be started again so it can download the new version. Click Start if it is down, or run a daily restart from the Schedules tab. The Mods tab also installs, updates and removes mods.
Game updates are separate. When the Steam update bar at the top of the page says an update is out, click Update now (a running server stops and starts again by itself). The game's Enable_Update_Shutdown and scheduled shutdown options are in the gameplay config (Config.json on the Configs tab, stop first), but on the panel a Schedules task covers the roughly daily restart the official docs recommend.
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 the map on the Startup tab matches the folder name exactly |
| Item missing after restart | Look for a download error on the Console tab; 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 the gameplay config (Config.json on the Configs tab) 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 Console tab for the update message, then Start the server |
| 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 output from the Console tab and the contents of Configs, Workshop mods. Those two things answer most questions. The Troubleshoot tab lists crashes and failed starts with likely causes.
Frequently asked questions
Where do I put the Workshop ID on an Unturned server?
On the Mods tab, or in the File_IDs list in Workshop mods on the Configs tab, 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 on the Startup tab 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. It has to be started again to download the new version: click Start, or use a daily restart on the Schedules tab.