To install a mod on a Vintage Story dedicated server, stop the server, download the release that matches the server’s exact Vintage Story version, and place the mod’s .zip file—without extracting it—in a directory listed by the server’s ModPaths setting. The default data directory described by the official dedicated-server guide is %AppData%/VSserverData/Mods, but a custom dataPath or ModPaths value in serverconfig.json can change it. Restart the server, read the startup log for load errors, then connect and test the feature. Server-side and universal mods can normally be supplied to players automatically; client-side mods still require each player to install them.
What do I need before installing a Vintage Story server mod?
You need administrative access to the server’s data files, a way to stop and restart the server cleanly, and a backup of the world. Plan the change for a maintenance window because adding, replacing, or removing archives while the process is running can leave the server using a mixture of old and new files.
- Server access: You must be able to reach the persistent data directory and edit
serverconfig.jsonif the installation uses a custom path. - A compatible release: Check the mod’s Files entry in the official Vintage Story Mod DB and select a file that explicitly supports the Vintage Story version running on your server.
- A current backup: Copy the save before installing, updating, or removing a mod. World-generation and content mods can alter blocks, items, entities, assets, or mappings in ways that are difficult to undo.
- A restart window: The server must be offline while you copy, replace, or delete mod archives and while you change path settings.
- The correct mod type: Determine whether the release is server-side, universal, or client-side so you know what joining players will need.
How do server-side, universal, and client-side mods differ?
| Mod type | Where it runs | What the administrator does | What a player does |
|---|---|---|---|
| Server-side | Only on the dedicated server | Install the archive in a server mod path and verify it in the log. | Normally nothing extra; the player connects with the standard client. |
| Universal | On both server and client | Install it on the server. The server can offer the required file to clients. | From Vintage Story 1.16 onward, the client can download and maintain a server-specific copy automatically. |
| Client-side | Only on an individual player’s client | Installing it on the server does not distribute it as a server requirement. | Install it in the normal client Mods folder or follow the mod’s server-specific instructions. |
A mod page may describe more than one role, so read its compatibility and installation notes rather than relying on the file name alone.
Where is the Mods folder on a Vintage Story dedicated server?
The official dedicated-server guide gives %AppData%/VSserverData/Mods as an example of the server data Mods directory. Your server may use another location: dataPath determines the data root, and the ModPaths setting in serverconfig.json determines which directories Vintage Story scans for mods.
How do I find the directory the server actually scans?
- Stop the server process completely.
- Open the server’s
serverconfig.jsonin the data directory used by the installation. - Read the
dataPathandModPathsvalues. Resolve relative paths from the configured data root, and note every directory listed byModPaths. - Use one of those directories for the mod archive. If the directory does not exist, create it with the exact name and location specified by the configuration.
- Save configuration changes before restarting. A ZIP placed beside the server executable, in a temporary upload folder, or in a client-only Mods directory will not load unless that location is included in
ModPaths.
Do not confuse the dedicated server’s Mods path with a player’s ordinary local Mods folder. The server reads its configured data paths; a player’s game reads the client paths on that computer.
How do I install a mod on the server?
Use this sequence for each initial installation or replacement. Keeping the server offline during the file operation makes the result reproducible and gives the log a clear start point.
- Stop the server. Use the hosting control panel’s stop action or the method documented for your service. Wait until the process has exited rather than merely closing a console window.
- Back up the world and configuration. Preserve the save,
serverconfig.json, and the existing Mods directory. A backup gives you a rollback point if the new release changes world data or prevents startup. - Open the mod’s Files entry. In the official Vintage Story Mod DB, identify the file whose supported Vintage Story version matches the version shown by your server. The newest upload is not automatically the right one: a later mod release can drop support for an older game version.
- Download the archive. Confirm that the downloaded file is the release archive intended for Vintage Story, normally ending in
.zip. Do not substitute a source-code download or an archive for another game version. - Copy the ZIP into a scanned path. Place the file directly in a directory named by
ModPaths, such as%AppData%/VSserverData/Modswhen that is the configured data location. - Leave it compressed. The official wiki’s instruction is: “Do not extract the mod zip. Just place the .zip file into your Mods folder, that’s all you need to do.” Do not create an additional folder by unpacking the archive unless the mod’s documentation explicitly describes a separate asset or configuration step.
- Check for duplicate copies. Remove older or accidental copies of the same mod from every scanned path. When duplicate versions are present, Vintage Story attempts to load the highest version, which can produce an unexpected combination of files.
- Start the server. Perform a full restart after copying the archive or changing configuration. A running process will not reliably adopt a file that was added or replaced underneath it.
- Read the startup log. Look for the mod being discovered and for dependency, version, or loading errors. If the server reports an incompatible release or fails during startup, stop it and restore the backup before trying another version.
- Connect and test. Join with a test account, check the feature the mod is supposed to provide, and watch the server log while entering the world. Only invite the rest of the players after the server starts cleanly and the expected behavior is present.
Do players need to install the same mods?
Not always. The answer depends on the mod category and whether the server offers a universal package to connecting clients.
Server-side mods
A server-side mod runs only in the server process. Players normally do not install a second copy, because the client does not need the mod’s code to participate in the server’s rules. They still need the same Vintage Story game version and any client requirements identified by the server or mod author.
Universal mods
A universal mod contains work needed on both sides. The server can offer the required file to players during connection. The official wiki states that, starting with Vintage Story 1.16, connecting to a multiplayer server that offers a modded game can automatically set up the appropriate mods on the player’s side.
Automatic setup uses a server-specific directory under %AppData%/Roaming/VintagestoryData/ModsByServer. This keeps the copy associated with that multiplayer server instead of treating it as a global installation. Players should still close the game or leave the server before changing local files.
Client-side mods
A client-side mod changes an individual player’s interface, rendering, controls, or other local behavior. The server does not automatically provide every client-only file. Each player must install such a mod in the normal client Mods folder or use the mod’s documented server-specific setup, and players without it may still be able to join because it is not part of the server’s required content.
How do I verify Vintage Story version compatibility?
Match the server’s game version to the compatibility information for the specific file, not merely to the mod’s project page or latest release date.
- Determine the exact Vintage Story version running on the server.
- Open the mod’s Files list and inspect the supported-game-version field for each release.
- Choose the newest file that still lists your server version. If the latest release lists only a newer game version, select an older compatible release instead.
- Check dependency notes and dedicated-server support before copying the file. A mod that works in a local single-player installation may not support a dedicated-server environment.
- Keep one intentional copy of each mod in the scanned paths. Delete obsolete archives so the loader cannot select an unintended higher version.
Version mismatches can range from a feature that silently fails to a startup crash or a world that cannot be loaded. Treat a clean download and a matching version as prerequisites, not as optional troubleshooting steps.
How should I update or remove a server mod?
Handle updates and removals as controlled migrations, not as ordinary file replacements. The world may already contain data created by the mod.
Safe update procedure
- Announce a maintenance window and stop the server.
- Back up the save, configuration, and current Mods directory.
- Remove or move the old archive so only the intended release remains in a scanned path.
- Copy the new, version-compatible ZIP without extracting it.
- Start the server and inspect the complete startup log before allowing players back in.
- Test a representative area of the world, especially features generated or placed by the mod.
Change a small set of mods at a time. If several archives are replaced together and the server then fails, isolating the offending change becomes much harder.
What can happen when a mod is removed?
Removing a mod from an established world can produce missing-asset, block, item, entity, or remapping warnings. World-generation and content mods are especially sensitive because existing chunks may reference data that no longer exists. If the server does not start or the world displays missing content, stop it, restore the backup, and reassess whether the mod can be removed safely.
Why is a mod missing, crashing, or not changing anything?
Most installation failures come from a wrong path, an extracted archive, an incompatible release, a stale client copy, or a restart that never occurred. Work through the symptom that matches what you see.
The mod is absent from the server’s mod list
- Confirm the filename still ends in
.zip; an extracted folder is not the instructed installation format. - Verify that the file is directly inside a directory listed by
ModPaths, not merely somewhere under the server’s main folder. - Recheck
dataPathand relative-path resolution inserverconfig.json. - Stop and restart the server, then inspect the new startup log.
- Remove duplicate copies from other scanned directories.
The server reports a load error or crashes
- Check the mod file’s supported Vintage Story version against the running server version.
- Read the mod’s notes for dedicated-server support and required dependencies.
- Undo the most recent change using the backup, then add compatible files one at a time.
- Do not continue inviting players while the server is starting with unresolved errors.
Players cannot join after the installation
- Compare the server’s Vintage Story version with each player’s client version.
- Identify whether the mod is server-side, universal, or client-side.
- For a universal mod, allow the client’s automatic server-specific download to complete; for a client-side mod, give players the installation instructions required by that release.
- Check the server log for a required-mod or version mismatch message.
A player has an old server-provided copy
Have the player leave the server and close the game. Delete the subfolder for that server under %AppData%/Roaming/VintagestoryData/ModsByServer, then reconnect so Vintage Story can download the offered files again. This targets the server-specific cache rather than the archive in the administrator’s data directory.
The change does not apply after replacing a ZIP
Make sure the process was fully stopped before the replacement, confirm that the new file is in a configured path, and perform a full restart. Then read the fresh log rather than relying on an old console message; a process that remained running may still be using the previous archive.
What should I look for in managed hosting?
If someone else operates the machine, the installation still requires the same five operational controls: a persistent server data Mods directory, a clean stop and restart function, visible server logs, reliable backups and rollback, and a clear policy for distributing client files.
| Capability | Why it matters | Question to ask the host |
|---|---|---|
| Persistent Mods directory | Files must survive restarts and be located in a path the server scans. | Can I upload ZIP archives to the directory named by ModPaths? |
| Clean stop and restart | Archives and configuration should not be changed while the process is writing or loading. | Can I stop the server fully, replace files, and start it again? |
| Log access | Load errors, dependency failures, and version mismatches are diagnosed from startup output. | Can I view or download the complete server log after a restart? |
| Backups and rollback | Worlds may contain mod-created blocks, items, entities, and mappings. | Can I make and restore a save backup before an update? |
| Client-file handling | Universal mods may be offered automatically, while client-only mods still need player action. | Does the server permit normal Vintage Story mod distribution, and which files remain manual for players? |
A control panel that only provides a file browser but no restart or log access leaves you without the checks needed to diagnose a failed load. Confirm these capabilities before moving an established world.
What is the safest repeatable workflow?
For a small server, this checklist keeps installations consistent:
- Record the server’s Vintage Story version and the mod release version.
- Classify the mod as server-side, universal, or client-side.
- Stop the server and create a dated save backup.
- Confirm
dataPathand every directory inModPaths. - Place one compatible
.zipdirectly in the selected Mods directory. - Remove unintended duplicate copies.
- Restart and read the startup log from the new run.
- Connect with a test player and verify the mod’s actual feature.
- For universal content, confirm that a client receives a server-specific copy; for client-only content, distribute separate player instructions.
- Keep the backup until the world has been played successfully and the change is considered stable.
Following this order separates path problems from compatibility problems and gives you a known-good rollback if an update damages an established world.
Frequently Asked Questions
Does deleting a server’s ModsByServer folder remove my normal single-player mods?
No. The ModsByServer location stores copies associated with multiplayer servers, while the ordinary client Mods folder is separate. Removing one server’s subfolder is therefore a way to refresh that server’s downloaded files without intentionally removing unrelated local installations.
Can I keep several releases of the same mod in different server folders?
Yes, provided each server’s configured paths and each client’s server-specific directory remain separate. Within the paths scanned by one server, however, duplicate archives can cause Vintage Story to choose the highest version, so keep only the release intended for that server.
What should I do if a mod works in single-player but not on my dedicated server?
Check the release notes for dedicated-server support and verify that every required dependency is present in a server-scanned path. A local installation can include client files or settings that a dedicated server does not load, so reproduce the test with the server stopped, the correct ZIP, and a fresh startup log.
Will updating a universal mod automatically update every player immediately?
Players receive the files offered by the server when they connect, but an existing stale server-specific copy can interfere. Have an affected player leave, remove that server’s subfolder under ModsByServer, and reconnect to force a fresh server-specific download.