VS Guide HubIndependent fan guide
English
Guide menu
A detailed library and cartography room built in Vintage Story.
Official Vintage Story screenshot · Official Vintage Story media
05 · Mods

How to Install Vintage Story Mods

Use the official Vintage Story Mod DB, choose a file that explicitly supports your game version, and place the downloaded .zip file in the user Mods folder without extracting it. For the current stable game, check compatibility with 1.22.5 on each mod’s Files tab before installation. Back up important worlds before adding, removing, or updating mods. Then enable or disable the mod through the in-game Mod Manager. If a problem appears, reproduce it in a new world or a copy and isolate the responsible mod before changing your main save.

Last Verified: August 14, 2026Stable 1.22.5

Recovery-first workflow

Back up, keep the package, isolate the conflict

Make every mod change reversible before you test it.

  1. Recover

    Back up the world

    Copy the save before adding, removing, or updating mods.

  2. Install

    Keep the .zip

    Use a compatible packaged .zip; do not unpack it into loose files.

  3. Diagnose

    Isolate

    If the game breaks, test a small set and restore dependencies one at a time.

Before downloading a mod

The official Vintage Story Mod DB is the main discovery and distribution site recommended by the community-maintained wiki hosted on the official Vintage Story infrastructure. A popular mod is not automatically safe for your current setup. Read its description, dependencies, side designation, supported game versions, file history, and recent issue reports.

CheckWhat to confirm for version 1.22.5
Game compatibilityThe selected file lists support for 1.22.5 or a compatible 1.22.x range stated by the author
DependenciesEvery required library or companion mod is installed at a compatible version
Client/server sideThe mod is installed where its Mod DB page says it must run
Existing overlapAnother enabled mod does not replace the same mechanics, assets, or registrations
World impactYou understand whether removing the mod later could delete blocks, items, entities, or world data
BackupA copy of the affected save exists outside the active save folder

Do not assume the newest mod file is the correct one. The official troubleshooting guide specifically warns that a newer mod version may target a different game release. The Files tab is the authoritative place to match a mod build to the game version you are actually running.

Install a mod in single-player

  1. Download the chosen mod file from its official Mod DB page.
  2. Leave the mod packaged as a .zip file unless its author explicitly provides different instructions. The standard installation does not require extracting the archive.
  3. Start Vintage Story and open Mod Manager from the main menu.
  4. Select Open Mods Folder. This avoids guessing which user-data folder your installation currently uses.
  5. Copy or move the mod .zip into that folder.
  6. Return to Mod Manager and choose Reload Mods, or close and restart the game.
  7. Confirm that the mod appears and is enabled. Keep the built-in Essentials, Survival, and Creative Mode entries enabled; together they provide the standard game.
  8. Test the change in a new world or disposable copy before committing a valuable long-running world.

On Windows, the default user mod path is %appdata%\VintagestoryData\Mods. On Linux, the official guide lists ~/.config/VintagestoryData/Mods. Using the Mod Manager’s button is safer when you have customized the data path or moved an installation.

Backups and updates

The official mod guide recommends backing up saves before adding a mod, removing a mod, or updating Vintage Story. Extend that habit to major mod updates as well. A backup should be a separate copy, not merely another file inside the same active save folder.

When updating a mod:

  1. Stop playing and close the game or server.
  2. Read the mod’s changelog for migration instructions or breaking changes.
  3. Back up the world and relevant configuration files.
  4. Remove the old duplicate archive if the new file uses a different name.
  5. Install the compatible replacement and confirm that only one active copy remains.
  6. Load a test copy first and inspect mod-specific blocks, inventories, entities, and recipes.

Troubleshooting checklist

SymptomFirst checksSafe next action
Mod does not appearWrong Mods path, invalid archive, stale custom modPathsOpen the folder from Mod Manager; if the OS username changed, inspect clientsettings.json and serverconfig.json paths while the game is closed
Game fails after an updateMod does not support 1.22.5Disable non-vanilla mods and install versions explicitly compatible with the current game
Missing blocks or startup exceptionsDuplicate versions of the same code modSearch all configured mod paths and keep only the intended copy
Crash appears only with several modsConflict between two modsReproduce in a test world and disable half the set at a time until the responsible mod is isolated
World works without mods but not with themDependency, version, or load-side mismatchCheck the Mod DB Files tab, dependencies, and client/server requirements
Modded server keeps an old fileCached server-specific mod has the same filenameLeave the server, delete its folder under ModsByServer, then reconnect to download the server set again

Do conflict testing on a new world or a copy. Enabling and disabling content mods repeatedly in the only copy of a valuable world can remove or remap data and make the original problem harder to diagnose.

Mods in multiplayer

Modern Vintage Story clients create a server-specific folder under ModsByServer when joining a modded server. Server-side or universal mods offered by the server can be downloaded for that server without mixing them into the player’s normal single-player Mods folder. Client-only mods may still require manual installation, depending on the mod and server policy.

Server owners should keep the server, its mods, and connecting clients on compatible versions. Make mod changes while the server is offline, back up the world first, and test the full set locally before reopening a public server. See the Multiplayer guide for data paths, ports, and update safety.

Frequently asked questions

Should I unzip a Vintage Story mod?

Usually no. The official installation guide says most mods are downloaded as .zip files and should be placed directly in the Mods folder.

Can a mod for an older release work on 1.22.5?

Possibly, but do not guess. Use the compatibility information on the mod’s Files tab and any instructions from its author.

Why are Essentials, Survival, and Creative Mode listed as mods?

Vintage Story builds its standard game through its own mod system. Those three entries are the vanilla game and should normally remain enabled.

How do I find the mod causing a crash?

Create a repeatable test in a new world or copied save, disable half of the non-vanilla mods, and continue halving the suspected group. This binary-search approach is much faster than testing one large list at random.

Public Sources