How to install mods for Vintage Story

Download from the official mod repository, upload zip files directly to your Mods folder, and explore verified community additions.

Updated August 10, 2026

Vintage Story

This guide covers adding mods to your Vintage Story server. For first boot and connecting, see Getting started with your Vintage Story server.

Vintage Story has an excellent modding ecosystem at mods.vintagestory.at.

Step 1: Download Mods

Each mod is a .zip file (just a renamed mod archive) or .dll. Download from ModDB.

Step 2: Add the Mods to Your Server

Add the mod files to the server's Mods/ folder via SFTP.

Mods/
  PrimitiveSurvival.zip
  XSkills.zip
  Carryon.zip

text

Step 3: Restart

The server loads mods at boot. The console will list each one.

Players need the same mods on their client

Players must install the same mods on their client (Vintage Story has a built-in mod manager that simplifies this).

Players: Installing the Same Mods on Your Client

Since Vintage Story 1.16 this is mostly automatic. The official wiki states that on connecting to a modded server "your game will automatically set up the mods correctly for that server on the player's side", downloading them into a per-server subfolder rather than mixing them into your own mods:

Windows   %appdata%\VintagestoryData\ModsByServer
Linux     ~/.config/VintagestoryData/ModsByServer
macOS     ~/Library/Application Support/VintagestoryData/ModsByServer

text

To install a mod for yourself — single player, or something the server does not require — use your own Mods folder instead:

Windows   %appdata%\VintagestoryData\Mods
Linux     ~/.config/VintagestoryData/Mods
macOS     ~/Library/Application Support/VintagestoryData/Mods

text

Drop the .zip in without extracting it. The quickest way to find the folder is from the game: main menu, Mod Manager tab, Open Mods Folder. Reload Mods on the same screen picks up a new mod without restarting, and the Mod Manager is also where you enable and disable mods per session.

macOS moved

~/Library/Application Support/VintagestoryData is the path from 1.21.0 onwards. Earlier builds used ~/.config/VintagestoryData on macOS as well as Linux.

Version mismatches are what stops people connecting

The wiki is blunt: you "will likely be unable to join the server (or you might experience crashes) unless your mod set-up - including version numbers - exactly matches the mods the server requires". The right mod at the wrong version is still a mismatch. On ModDB every mod has a Files tab listing which game versions each release is built for — match against your server's game version, not just the mod name.

Updating and Configuring Mods

Configuration. Most mods write their settings on first boot rather than at install time, so there is nothing to edit until the server has started once with the mod loaded. Look in ModConfig/ in the server's data folder — the wiki describes it as where "each mod may optionally create a json file in this folder for configuration settings". One .json per mod, named after the mod. Stop the server before editing; those files are read at startup.

Updating. Replace the .zip and restart. Delete the old one rather than leaving both in Mods/ — multiple copies of the same mod is a documented cause of instantiation errors, and the server will try to load both.

Where the server looks. serverconfig.json has a ModPaths list, which is "where server should look for mods". It defaults to Mods and accepts absolute paths too, which is worth knowing if you want one mod folder shared across worlds.

Common Issues

A mod does not appear in the console list or the Mod Manager. Almost always the wrong game version. Check the mod's Files tab on ModDB for a release built for the version you run.
The server starts fine but players cannot connect. Mod set mismatch, version numbers included. Have a player delete that server's subfolder under ModsByServer and reconnect so the game fetches everything fresh.
A mod works alone and breaks in combination. Conflict. Disable half the mods, test, then halve again until you find it. Tedious, but it is the method the wiki recommends and it beats reading changelogs.
Errors naming the same mod twice. Two copies in Mods/, usually an old .zip left behind after an update. Keep exactly one.