A Vintage Story mod server is a normal dedicated server with mod .zip files in its data folder’s Mods folder, and the game does the rest. Players who join get a prompt to download the server’s mods from the official ModDB automatically, so nobody has to copy files by hand. To add mods to a Vintage Story server, drop the zips in that folder (don’t extract them) or run /moddb install modid in the console, then restart. Here is each step, plus how server-side and client-side mods differ.
Does Vintage Story have mod support?
Yes, and it is built in. The base game itself ships as three mods, Essentials, Survival and Creative, so modders get the same engine access as the developers. The official ModDB at mods.vintagestory.at lists more than a thousand mods. Since 1.16 a modded multiplayer server sets up each player’s mods automatically when they connect.
You can use mods on a dedicated server you run yourself or on Vintage Story server hosting. The only hard rule is versions: every mod release is built for certain game versions, and your server, your mods and your players’ game should all match.
Where the Vintage Story server mods folder is
The server mods folder is Mods inside the server’s data folder, the same folder that holds serverconfig.json, Saves and Logs. That is %AppData%\VintagestoryData\Mods on Windows, ~/.config/VintagestoryData/Mods on Linux, or <dataPath>/Mods if you start the server with --dataPath.
- Not the install folder: the server’s program folder has its own
Modsfolder with a file calleddo_not_add_mods_here.txt. It is reserved for the three base-game mods. Put your mods in the data folder. - Extra folders:
ModPathsinserverconfig.jsonlists every folder the server loads mods from, and--addModPathadds one at launch. - Keep the zip: mods are read straight from the
.zip, and the wiki says not to extract them.
How to add mods to a Vintage Story server
There are two ways to install mods on a Vintage Story server: upload the .zip into the Mods folder, or install by ID with /moddb install from the console. Both end the same way: restart the server so it loads the mod. Back up the world first, as the wiki advises before every mod change.
Method 1: upload the .zip
- Back up: run
/genbackup, or copy theSavesfolder. - Download the release from the mod’s ModDB page that matches your server’s game version.
- Stop the server.
- Copy the
.zip, unopened, into the data folder’sModsfolder. Add any mods it lists as dependencies too. - Start the server and check the log, or run
/moddb list, which answers “N 3rd party mods installed” with their names.
Method 2: install from the console with /moddb
The server can fetch mods from the ModDB itself. You need the mod ID, which is shown on the mod’s ModDB page and is often the last part of its address: Carry On is carryon.
/moddb search carryon find a mod for your current game version
/moddb searchcompatible carryon include releases marked compatible with your version
/moddb install carryon install the right release
/moddb install carryon 1.22.7 or name the game version yourself
/moddb list see what's installed
/moddb remove carryon uninstallRestart afterwards. If the server answers “No such version is listed on the moddb”, the mod has no release for that game version yet. “Command not available. Disabled probably by the host” means your host has switched /moddb off, so use the file upload instead. More admin commands are in Vintage Story server commands.
Vintage Story server side mods, client side mods and universal mods
Every Vintage Story mod declares which side it runs on: Server, Client or Universal (both). The ModDB shows this on each mod page. Universal is the default, and it is the type players must have to join: the game offers to download those for them. Server-side mods run on the server only. Client-side mods stay each player’s own choice.
| Side | Where it goes | Do players need it? | Typical examples |
|---|---|---|---|
| Universal (ModDB: “both”) | Server Mods folder |
Yes, downloaded automatically on join | New blocks, items, creatures, recipes, worldgen |
| Server | Server Mods folder |
No | Admin tools, server-only logic |
| Client | Each player’s own Mods folder |
Optional, per player | Shaders, HUD and interface tweaks |
A mod author can also mark a universal mod as not required on the client (requiredOnClient: false), so players without it can still join. Some mods work both ways. ProspectTogether, for instance, works client-only for your own prospecting notes, but has to be on the server too if you want to share them with the group.
Controlling Vintage Story client side mods on your server: add a mod ID to ModIdBlackList in serverconfig.json, or run /serverconfig modblacklist add modid, and players with that mod enabled are turned away. /serverconfig modwhitelist keeps the opposite list of allowed mod IDs. All the other keys are in Vintage Story server settings explained.
How players join a modded server
Players join a Vintage Story server with mods the same way as a vanilla one. When they connect, the game says “You are missing N mods to join this server, shall I attempt to download them from the mod database?” They accept, wait for “All mods downloaded, ready to join this server!”, and they are in. Their own singleplayer mods aren’t touched.
- Downloaded mods go to a per-server folder in
VintagestoryData/ModsByServeron each player’s PC. - The download comes from the ModDB. A mod that isn’t on the ModDB (a private build, a forum-only file) has to be installed by each player by hand. Otherwise they see “Sorry, cannot connect, you need the following mods installed”.
- “A mod requires v… of the game” means the player’s game is older than a mod needs. They update the game.
Popular Vintage Story server mods
Each mod below has hundreds of thousands of downloads on the ModDB and, when we checked, all had releases for 1.22. All are universal, so players get them on join. Treat this as a starting point, not a ranking. Check each mod’s page for your exact version and its dependencies before installing.
| Mod | Mod ID | What it adds |
|---|---|---|
| Carry On | carryon |
Pick up placed blocks, including chests with their contents, and carry them |
| Primitive Survival | primitivesurvival |
A harder, more realistic early game: snares, weir traps, fences from stakes and cordage |
| ProspectTogether | prospecttogether |
Records prospecting readings on the map and shares them with your group |
| Smithing Plus | smithingplus |
Smith with metal bits and nuggets, add bits back to a work item |
| BetterRuins | betterruins |
Many more handcrafted ruins and story locations to explore |
| Config lib | configlib |
In-game settings screens for other mods. Needs ImGui (vsimgui) |
Want to join Vintage Story modded servers instead of building your own? Browse the public list at servers.vintagestory.at or Browse public servers in the Multiplayer menu. There’s no single best server: pick one by region, mod list and play style. For Vintage Story official server mods and community ones alike, the source is the same official ModDB.
Adding or removing mods mid-game
You can add most mods to an existing world. New items and recipes work right away after a restart. Mods that change world generation, such as new ruins or ores, only affect chunks generated after you add them, so players have to explore new land to see them. Removing a mod is riskier: blocks and items from it break in the world.
- Before any change:
/genbackup. - After removing or updating a mod with custom blocks:
/birremaps block IDs to fix broken blocks. - Updating the game: update every mod to a release for the new version at the same time, then restart.
- Turning a mod off for one world:
DisabledModsin theWorldConfigblock lists mod IDs to ignore.
Troubleshooting a Vintage Story server mod install
Most mod problems on a Vintage Story server are a version mismatch, a mod in the wrong folder, or a stale copy on a player’s PC. Check the server’s Logs/server-main.log first: a mod that fails to load says so there, usually with its name. Then work through the table.
| Problem | Fix |
|---|---|
Mod doesn’t show up in /moddb list |
Wrong folder (use the data folder’s Mods), extracted zip, or no restart |
| Server crashes on start after adding a mod | Wrong game version or a missing dependency. Remove the newest mod and read the log |
| “Disconnected, modded server with lacking mods on the client side” | The player declined or failed the download. Rejoin and accept |
| Player crashes or loops downloading on join | Delete that server’s subfolder in ModsByServer and rejoin |
| “Some of your added mods have missing dependencies” | Install the listed dependency mods too |
| “Command not available. Disabled probably by the host.” | /moddb is off on that server. Upload the zip |
| Player can’t join after you blacklist a mod | They have a mod from ModIdBlackList enabled. Disable it on their side |
| Code mods fail on a Raspberry Pi server | The ARM64 server doesn’t support mods that use Harmony patching |
New to running a server at all? Start with the Vintage Story dedicated server guide.
Skip the setup: mods by request
On GameTeam’s Vintage Story server hosting you don’t need to find mod IDs or folders. Tell the AI copilot “install Carry On and ProspectTogether for 1.22, back up first” and it makes a backup, puts the right releases in the server’s Mods folder, restarts, and reads the log to confirm both loaded. If a mod breaks the server, ask “why won’t it start?” and it points to the mod in server-main.log. You pay per GB of RAM, from $0.49/GB a week (or $1.99/GB billed monthly), with unlimited slots, so a big mod list only means picking more RAM.
FAQ
Can you use mods on a Vintage Story server?
Yes. Put the mod zips in the server’s Mods folder or use /moddb install, and players are offered the mods automatically when they join.
How do I import mods into a server?
Upload the .zip files, unextracted, to the Mods folder in the server’s data folder, then restart. On a host, use the file manager or FTP for the same folder.
Do players need to install the server’s mods themselves?
Not for mods from the ModDB: the game downloads them on join. Only mods that aren’t on the ModDB, and optional client-side mods, are installed by each player.
How do I add Vintage Story mods mid-game?
Back up, add the mod, restart. Content appears right away; new worldgen only shows in land nobody has explored yet.
How much RAM does a modded Vintage Story server need?
Start from the developers’ estimate of 1 GB plus about 300 MB per player, then add headroom for mods. A big mod list on a busy server usually wants more than the 4 to 6 GB a vanilla group needs. Watch memory in /stats.
Where do I get Vintage Story mods?
From the official ModDB at mods.vintagestory.at. A few more are posted on the official forums.