How to install Vintage Story mods for singleplayer and multiplayer

The short installation answer

For singleplayer, choose a mod release compatible with your Vintage Story game version, resolve its required dependencies, and place the unextracted ZIP file in the user data Mods folder. Open the in-game Mod Manager to reload, enable or disable projects.

The official guide identifies the normal Windows folder as %appdata%\VintagestoryData\Mods and the normal Linux folder as ~/.config/VintagestoryData/Mods. Opening the folder through the Mod Manager avoids confusing it with the separate Mods folder inside the game installation.

Choose the release before moving the ZIP

A project may publish files for several Vintage Story versions. Pick one that names the game version you run; a similar filename or newer upload does not make it compatible.

Then check its libraries. Vintage Story uses mod IDs and version comparisons, so the right project at the wrong version can still fail. We use the exact release data our API has and show you when part of the chain is missing.

Install for singleplayer

1. 01

   Copy the world or back up the complete Vintage Story data directory.

2. 02

   Confirm the game version shown on the main menu.

3. 03

   Select a matching mod release and every required dependency.

4. 04

   Use Mod Manager → Open Mods Folder to open the user data Mods directory.

5. 05

   Move the downloaded mod ZIP files into that folder without extracting them.

6. 06

   Reload mods or restart the game, then check every project and version in Mod Manager.

7. 07

   Open a temporary world before testing a copied established save.

Multiplayer can synchronise required server mods

The official Vintage Story guide says that, from version 1.16, joining a modded server can set up the server’s offered mods in a server-specific ModsByServer subfolder. That keeps one server’s required set separate from another server and from the ordinary singleplayer Mods folder.

Automatic transfer does not make every local project server-compatible. You can still have client-only additions, and a stale same-named file can occasionally prevent the updated server copy from being obtained. If a known server update behaves incorrectly, leave the server, remove only that server’s generated ModsByServer subfolder and reconnect.

Side and required-side fields answer different questions

A release can be client, server or universal. Universal says where its code can run, while requiredOnClient and requiredOnServer determine whether the universal mod may be absent from either side. Do not simplify those fields into a single “both” badge.

For a dedicated server, install the matching server-required and universal files plus their libraries. Keep client-only visual or interface mods out unless the creator says they also do something on the server.

If the game reports a missing or incompatible mod

• Verify the game version and the exact release version shown by Mod Manager.
• Check the required mod id as well as the display name.
• Resolve each dependency recursively instead of stopping at the first library.
• Look for a duplicate older ZIP in both the user data and game-installation Mods folders.
• Test without optional projects, but preserve every required dependency.
• Restore the world backup if removing a content mod changes or deletes saved objects.