VS MODDB

How to Install Vintage Story Mods

One command handles most of it — /moddb install — but knowing the right mod ID, dependencies and folder structure is where people actually get stuck.

Modding is easier here than in most survival games

If you’ve dealt with mod installs in other games, Vintage Story is refreshingly simple in one specific way: players don’t need to do anything. Since version 1.16, the client automatically detects and downloads the mods a server is running the moment you connect — no matching versions by hand, no separate download links to chase down. That’s a genuinely different experience to games like DayZ, where every player has to manually track down and install the exact same mod list as the server. See our guide to playing with friends for how that plays out on the joining side.

What’s left is the server owner’s side: getting mods onto the server itself. That’s what this guide covers.


Installing mods on your Vintage Story server

Two methods exist — an in-game command that pulls straight from the mod database, and a manual upload for anything it can’t find. Most people only ever need the first one.

1
Find the mod on VS ModDB and note its ID
Visit the official Vintage Story Mod Database and find the mod you want. The mod ID is usually the last part of its URL — for a mod at mods.vintagestory.at/primitivesurvival, the ID is primitivesurvival. There’s no fully consistent naming standard across every mod, so if the obvious guess doesn’t work in step 2, check the mod’s Files tab for the exact name.
2
Run the install command
Open your server’s console (on a rented server, the console in your host’s panel) or join in-game with admin permissions, and run:
/moddb install primitivesurvival
You’ll get a confirmation message once it downloads. The optional second argument is a game version, not a mod version: /moddb install primitivesurvival 1.22.7 fetches the release built for Vintage Story 1.22.7. Use /moddb searchcompatible primitivesurvival to see what’s available for your server’s version, and /moddb list to check what’s installed. If your host has disabled /moddb, use the manual upload in step 4.
3
Check for dependencies before you restart
Many mods rely on separate “library mods” to function, XLib being a common example. Check the mod’s ModDB page and description for its dependencies, and install those the same way, before assuming the main mod is broken.
4
If a mod isn’t in the database, upload it manually
Download the release that matches your server’s game version from the mod’s Files tab on ModDB, and keep it as a .zip: the official wiki says not to extract mod zips. Upload it via SFTP or your host’s File Manager into the Mods folder inside the server’s data folder (often shown as data/Mods). The server install folder has a second Mods folder, but that one holds the three base-game mods (Essentials, Survival and Creative) and is meant to be replaced when you update the game, so your own mods don’t belong there.
5
Restart the server
Both installation methods require a full server restart to take effect. Players connecting afterward will have the new mods set up automatically on their end, as covered above.
Worth knowing before you go further

Install mods a few at a time rather than dumping in a full list at once — not every mod on the database is actively maintained, and if something breaks, a small batch makes it far easier to identify which one caused it. Once you’re happy with your mod list, it’s worth reviewing our server settings guide too, since heavier modpacks are exactly when settings like MaxChunkRadius start to matter for performance.


Server-side vs client-side mods

Not every mod needs to go on the server at all. Every ModDB page lists a Side (Both, Server side or Client side) that tells you where it belongs:

Side: “Both” or “Server side mod”

Install these on the server. Server-side mods only run there, and mods marked Both are sent to players automatically when they join, per the automatic sync covered above, so players don’t need to install anything themselves.

Side: “Client side mod”

Usually visual or UI enhancements. These install only on an individual player’s own game and don’t need to touch the server at all — installing them there does nothing useful.


Common mod problems

What you see Likely cause Fix
“Mod not found” on install Guessed mod ID doesn’t match Check the mod’s Files tab on ModDB for the exact ID
Mod installed but not working Server not restarted, or missing dependency Restart the server; check the mod’s listed dependencies
Manually uploaded mod doesn’t load Wrong folder, extracted zip, or wrong game version Put the unextracted .zip in the data folder’s Mods folder and use a release for your game version
Players get errors connecting after a mod update Mod release doesn’t match the server’s game version, or players have a stale cached copy Install a release made for the server’s game version; players can delete that server’s folder in ModsByServer and rejoin

For anything not covered here — crashes, world corruption, connection errors — see our full Vintage Story server troubleshooting guide.


Vintage Story mods — common questions

No, not since Vintage Story 1.16. The client automatically downloads and sets up the server’s mods when connecting, storing them in a per-server folder inside VintagestoryData/ModsByServer. This is covered in more depth in our guide to playing with friends.
It’s typically the last segment of the mod’s URL on the Vintage Story Mod Database, though this isn’t fully standardised across every mod. If your first guess doesn’t install, open the mod’s page and check the Files tab, which usually lists the exact identifier to use.
Yes. The second argument of /moddb install is a game version, for example /moddb install primitivesurvival 1.22.7, which fetches the release built for that version of Vintage Story. To run one exact mod release, download that .zip from the mod’s Files tab and upload it manually instead.
Usually one of three things: the file went into the install folder’s Mods folder instead of the Mods folder inside the server’s data folder, the zip was extracted (keep it as a .zip), or the release doesn’t match the server’s game version. Also remember to restart the server afterward, which both installation methods require.
Yes, mods that add entities, blocks, or extra logic add directly to the server’s workload. Our server settings guide covers the specific settings worth adjusting once you’re running a heavier modpack.

Compare Vintage Story hosting providers

See our full Best Vintage Story Hosting comparison for pricing and hardware across every provider we compare, or start with a free trial server if you’re not ready to commit yet.

Similar Posts