How to Add Mods to a Vintage Story Server (1.22 Guide)

To add mods to a Vintage Story server, stop the server, put each mod’s .zip file, still zipped, in the Mods folder of the server’s data path (data/Mods on most servers), add every mod it depends on, then start it and check the Found N mods line in the log. Your friends don’t install anything by hand: when they join, the game offers to download the server’s mods. This guide covers the exact folders on Linux and Windows, how to check a mod’s version tags and dependencies on the ModDB before you download it, the log lines that prove each mod loaded, what your friends see, and the mistakes that make a mod silently disappear. Paths, commands and log lines are for Vintage Story 1.22; 1.22.7 is the current stable version.

Check each mod’s version, side and dependencies first#

Five minutes of checking saves the evening. Do these three things before you download a single file.

1. Back up the world

   The wiki asks for a backup before you add or remove a mod. On a running server, /genbackup copies the world into the data path’s Backups folder without pausing the game. On a stopped server, copy the .vcdbs file from data/Saves somewhere else.

2. Write down the server's game version

   The first lines of the server log say it: Game Version: v1.22.7 (Stable). Mods are tagged by exact game version, so you need the number, not just “1.22”.

3. Open each mod's page on the ModDB

   On mods.vintagestory.at, look at the mod’s Files tab: each release lists the game versions it is tagged for, and the description usually says what it requires.

Here’s what that check looked like for five popular mods on 5 October 2026, against a 1.22.7 server:

Two things in that table catch most first-timers. First, dependencies: Config lib does nothing without ImGui, and its page says so in one line (“Requires ImGui”). Download both, or the server loads neither. Libraries like these are why a list of 20 mods often ends up as 25 files. Second, the tags: Carry On’s newest release stops at 1.22.6 and ImGui’s at 1.22.3. That isn’t proof they’re broken on 1.22.7. The game itself only checks the minimum version written inside the mod, and a real 1.22.0 server log shows mods built for 1.21 loading fine. It does mean nobody tagged that exact combination, so test it on a copy of your world first.

The side column matters too. both (called Universal inside the mod) runs on the server and on every player’s PC. server mods run only on the server. client mods, like minimaps or shaders, belong on players’ PCs and do nothing on a server.

Add mods to a Vintage Story server: put each .zip in data/Mods#

A Vintage Story server has two Mods folders, and only one is yours. The server looks in both, which its log confirms on every start:

[Notification] Will search the following paths for mods:
[Notification]     ~/Mods
[Notification]     ~/data/Mods

The first one, Mods inside the server install, holds the three base mods that make up the game itself (Essentials, Survival and Creative). Many installs include a do_not_add_mods_here.txt file there, and the name is the instruction. Updating the server means deleting the old install, so anything you put there disappears with it. Your mods go in the second one, the Mods folder of the data path:

The ModPaths key in serverconfig.json decides which folders are searched. If you moved the data path and the log doesn’t list your folder, add it as the official Linux guide does, and keep the first entry:

"ModPaths": [
  "Mods",
  "/home/vintagestory/data/Mods"
]

The wiki is blunt about that first "Mods" entry: removing it stops the base game from loading. With the folder found, the install itself is three steps:

1. Stop the server

   Run /stop in the console, which saves the world and shuts down. The wiki says changes to the mod folder are “best done while the server is offline” and take effect at the next launch.

2. Copy every .zip into the data Mods folder

   One file per mod, dependencies included, exactly as the ModDB downloaded them. Don’t extract them and don’t rename them into folders.

3. Start the server

   Launch it the way you always do. A server with dozens of mods takes longer to start: a real 1.22.0 server with 66 mods took 50 seconds to finish.

Start the server and read the mod lines in the log#

A server that starts isn’t proof that every mod loaded. The log is. Open server-main.log in the data path’s Logs folder, or scroll the console, and look for these lines. This is from a real 1.22.0 server with a large mod list (rows shortened):

[Notification] Found 67 mods (0 disabled)
[Notification] Mods, sorted by dependency: biggerpockets, chiseltools, ..., vsimgui, ..., configlib, ...
[Notification] Instantiated 225 mod systems from 66 enabled mods
[Notification] Loaded mods (66):
ModID        Version  Name         FileName               Dependencies   Authors
chiseltools  1.17.1   chiseltools  ChiselTools1.17.1.zip  -              QPTech
configlib    1.11.1   Config lib   configlib_1.11.1.zip   vsimgui@1.2.0  Maltiez, The Insanity God

Found N mods counts every mod the server saw in its folders, including the base mods. Loaded mods is the table that matters: one row per mod that actually loaded, with its version, its file and what it depends on. Count your files against the table. If you copied 12 zips and a mod’s ID isn’t in the table, that mod didn’t load, and the reason is a few lines above.

The most common reason is a missing dependency. The game prints it as an error with the mod’s ID in brackets:

[Error] [yangtransport] Could not resolve some dependencies:
[Error] [yangtransport]     evilinteractionrangehack@6.9.0 - Missing
[Error] [yttdiagonals] Could not resolve some dependencies:
[Error] [yttdiagonals]     yangtransport@0.7.5 - Dependency 'yangtransport.zip' (yangtransport) has dependency errors itself

Read it from the bottom up: one missing file (evilinteractionrangehack, version 6.9.0 or newer) knocked out the mod that needed it and then every mod that needed that one. Download the missing mod from the ModDB, stop the server, add the zip and start again. The Dependencies column also tells you what not to remove later: in the table above, deleting ImGui would take Config lib down with it.

Have a friend join and accept the mod download#

The final check is a real player. When a friend clicks your server in Multiplayer, the game asks whether to download the server’s mod list. If they accept, it fetches every server-side and universal mod into a folder of its own for your server: %AppData%\VintagestoryData\ModsByServer on Windows, ~/.config/VintagestoryData/ModsByServer on Linux and ~/Library/Application Support/VintagestoryData/ModsByServer on macOS. Their own single-player mods aren’t touched. For the distinction between server, client and universal releases, see our Vintage Story mods reference guide.

Three things about that download decide whether the join works:

• It comes from the ModDB, not from your server. A mod you got from a Discord message or built yourself, which isn’t on mods.vintagestory.at, never reaches players. The server loads it, but players can’t fetch it, so they can’t join. Keep server-and-client mods to ones published on the ModDB.
• Client-side mods aren’t included. A minimap or a shader your group likes has to be copied by each player into that server’s ModsByServer folder, or installed normally.
• A mod re-uploaded with the same file name isn’t downloaded again. If a friend keeps crashing after an update, have them quit, delete your server’s subfolder in ModsByServer and join again for a fresh copy.

Everyone in the group still needs their own Vintage Story account from vintagestory.at, and plays on Windows, macOS or Linux; the game isn’t on Steam or consoles. If the friend gets in and the new blocks or items are in their handbook, you’re done.

Why /moddb install isn’t the route on 1.22.7#

Vintage Story has a console command that installs mods straight from the ModDB, and on paper it’s the quickest route. The official command list gives this syntax, available since 1.18:

/moddb install [modid] [gameVersion]
/moddb remove [modid]
/moddb list
/moddb search [query]
/moddb searchcompatible [modid]

On 1.22.7, /moddb install failed on our test servers with an error that ends “JSON integer … too large or small for an Int32”. Until a patch fixes it, use the file route above. The search commands are still handy for finding a mod’s ID from the console, and /moddb list shows what’s installed. Whichever route you use, the Loaded mods table in the log is still the proof, and dependencies still have to be there.

Give the server enough memory for the mod list#

Mods, and players spreading out across the map, are what push a Vintage Story server’s memory up. Anego’s own guidance is 1 GB plus 300 MB per player for the base game. On our servers, a freshly started 1.22.7 world used:

Those are the floor, not the ceiling: the figure grows as players spread out and the server loads more land. So 4 GB fits a vanilla or lightly modded group, a list of around 50 mods with players exploring is where 8 GB earns its keep, and 100+ mods or a large community call for 12 GB. On a home PC, also leave room for the game client if you play on the same machine. If a server runs out of memory mid-session, the safest move is to stop it and restore the backup, not to keep playing on a world whose land may have generated with gaps.

Let the Game Hosting panel do steps 1 to 3#

Everything above works on any host or home server. If you’d rather not track dependencies and version tags by hand, we recommend Game Hosting’s Vintage Story servers: the Mods tab searches mods.vintagestory.at from the panel, and you add a mod in one click or pin a specific version. On the next start, the server downloads the newest release for its 1.22 version together with every mod it depends on, so the libraries a mod needs arrive with it without you looking them up. Client-only mods are skipped with a notice instead of loading for nothing, and a mod ID that doesn’t exist stops the start with its name rather than leaving you to dig through the log.

The worlds are copied before every mod change, and the last 5 copies stay in .gamehosting/saves, so a bad mod list is a rollback, not a lost evening. The panel also warns when an author retracts a version you’re running or a newer one is out, and lists the mods that have no release yet for a new major version. Of the 36 Vintage Story hosts we reviewed in October 2026, about 8 have a ModDB installer, and only two of those resolve dependencies the way ours does.

Zips you upload yourself to data/Mods in the Files tab are kept alongside the panel’s mods, and one the server can’t read gets a plain warning in the console and is skipped. There’s no SFTP, so large uploads go through the web file manager. Plans have 4, 8 or 12 GB of memory, and if a modded server runs out, it’s stopped before it can damage the world and the panel says what to change.

Fix the first-install mistakes#

Most “my mod doesn’t load” reports come down to one of these. Find the symptom, then check the cause first.

If you’ve worked through the table and a mod still refuses to load, its ModDB page is the next stop: the comments and the issue tracker link usually show whether others hit the same thing on 1.22.7. Once the log’s table matches your folder and a friend has joined, take a fresh backup. That’s the copy to go back to the next time you add mods.