--- title: "How to install mods for Vintage Story" description: "Download from the official mod repository, upload zip files directly to your Mods folder, and explore verified community additions." url: "https://www.gameserverkings.com/knowledge-base/vintage-story/how-to-install-mods/" category: "Vintage Story" category_url: "https://www.gameserverkings.com/knowledge-base/vintage-story/" published: "2026-07-02T22:00:57.838Z" updated: "2026-08-10T09:27:46.148Z" source_format: "markdown" site: "GameServerKings" --- # How to install mods for 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](/knowledge-base/vintage-story/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. ```text Mods/ PrimitiveSurvival.zip XSkills.zip Carryon.zip ``` ## Step 3: Restart The server loads mods at boot. The console will list each one. > [!IMPORTANT] 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: ```text Windows %appdata%\VintagestoryData\ModsByServer Linux ~/.config/VintagestoryData/ModsByServer macOS ~/Library/Application Support/VintagestoryData/ModsByServer ``` To install a mod for yourself — single player, or something the server does not require — use your own `Mods` folder instead: ```text Windows %appdata%\VintagestoryData\Mods Linux ~/.config/VintagestoryData/Mods macOS ~/Library/Application Support/VintagestoryData/Mods ``` 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. > [!NOTE] 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. > [!IMPORTANT] 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. ## Popular Mods - **XSkills**: Skill tree progression system - **Primitive Survival**: New early-game options - **Carry On**: Pick up and carry larger objects - **CommonLib**: Required by many mods - **Stone Quarry**: Better stone gathering - **Wildcraft**: Plant and creature expansion - **A Culinary Artillery**: Cooking expansion - **Better Drifters**: Drifter (enemy) AI improvements - **Medieval Expansion**: Themed content The Vintage Story modding community is small but very high quality; most mods are well-maintained. ## What to Read Next - [Getting started with your Vintage Story server](/knowledge-base/vintage-story/getting-started-with-your-vintage-story-server/) for first boot and the basics - [Vintage Story Configuration](/knowledge-base/vintage-story/configuration-overview/) - [Vintage Story Admin Setup](/knowledge-base/vintage-story/how-to-add-admins-and-commands-vintage-story/) --- Made with 💜 by GameServerKings