Installing Mods
Enhance your Vintage Story server with mods from the community.
Best Practices
Before installing mods:
- Check RAM requirements - Mods significantly increase memory usage
- Match versions exactly - Mods must match your VS server version
- Backup first - Always backup before adding or updating mods
- Test one at a time - Add mods individually to identify issues
- Notify players - Players need the same mods installed
- Keep a mod list - Document installed mods and versions
RAM Recommendations with Mods
Mods significantly increase RAM usage. If you’re running a modded server, add extra RAM on top of the base requirements:
| Base Server | Light Mods | Heavy Mods |
|---|
| 4GB (8 players) | 6GB | 8GB+ |
| 6GB (16 players) | 8GB | 10GB+ |
| 10GB (32 players) | 12GB | 16GB+ |
Finding Mods
Official Mod Database
The official source for Vintage Story mods:
- ModDB - Official mod repository
Popular Mod Categories
| Category | Examples |
|---|
| QoL | Better inventory, waypoints |
| Building | Extra blocks, decoration |
| Survival | New mechanics, challenges |
| Animals | More creatures, farming |
| Technology | Advanced crafting |
Installing Mods
Step 1: Download the Mod
- Visit mods.vintagestory.at
- Find a mod compatible with your VS version
- Download the
.zip file
Step 2: Upload to Server
- Open Files in panel
- Navigate to the
Mods folder
- Click Upload
- Select the mod
.zip file
- Wait for upload to complete
Step 3: Restart Server
- Stop the server
- Start the server
- Check console for mod loading messages
Verifying Installation
In console, look for:
[Mod Loader] Loading mod: ModName
[Mod Loader] Mod ModName loaded successfully
Client-Side Setup
Important: Players need the same mods installed!
Installing on Client
- Download the mod from the same source
- Find your VS mods folder:
- Windows:
%appdata%\Vintagestory\Mods
- Linux:
~/.config/Vintagestory/Mods
- Mac:
~/Library/Application Support/Vintagestory/Mods
- Place the mod
.zip in the folder
- Launch the game
Mod Configuration
Many mods create config files in /data/ModConfig/:
- Stop server
- Navigate to
/data/ModConfig/
- Find the mod’s config file
- Edit settings
- Restart server
Essential Mods
Quality of Life
| Mod | Description |
|---|
| CarryCapacity | Carry more items |
| Better Ruins | Improved world gen ruins |
| More Classes | Additional character classes |
Content Expansion
| Mod | Description |
|---|
| Wildcraft | More plants and farming |
| Medieval Expansion | New items and mechanics |
| Primitive Survival | Extended early game |
Utility
| Mod | Description |
|---|
| Automapmarkers | Better map markers |
| ProspectTogether | Shared prospecting |
| Step Up | Auto-step blocks |
Mod Compatibility
Version Matching
Mods must match your server version:
✅ Mod for VS 1.19.x on VS 1.19.3 server
❌ Mod for VS 1.18.x on VS 1.19.x server
Checking Compatibility
On ModDB, each mod shows:
- Compatible game versions
- Dependencies
- Last update date
Server Configuration for Mods
Allow All Mods
In serverconfig.json:
Allow Specific Mods Only
{
"AllowAnyMod": false,
"AllowedMods": [
"modname1",
"modname2"
]
}
Updating Mods
Update Process
- Download new mod version
- Stop server
- Delete old mod file from
/Mods
- Upload new mod file
- Start server
- Notify players to update
Always backup before updating mods!
Removing Mods
Safe Removal
- Stop server
- Create backup
- Delete mod from
/Mods folder
- Check for related config files
- Start server
Removing content mods may cause world issues if mod items/blocks exist in the world.
Troubleshooting
Mod Not Loading
Check console for errors:
[Error] Failed to load mod: ModName
- Wrong VS version
- Missing dependencies
- Corrupted download
Mod Conflicts
Symptoms:
- Crashes on startup
- Features not working
- Strange behavior
Solutions:
- Identify conflicting mods
- Check mod compatibility notes
- Remove one of the conflicting mods
- Report to mod authors
Missing Mod on Client
Error: “Server requires mod X”
Solution: Player needs to install the same mod
Client Has Wrong Mod Version
Error: “Mod version mismatch”
Solution: Ensure server and client have identical mod versions
Best Practices
- Test mods individually - Add one at a time
- Keep a mod list - Document installed mods
- Regular backups - Before adding/updating mods
- Check compatibility - Before updating VS version
- Communicate with players - Announce mod changes
Creating a Mod List
Keep a mods.txt file for reference:
# Server Mods
- CarryCapacity v1.2.3
- Better Ruins v2.0.1
- Wildcraft v3.1.0
# Last Updated: 2024-01-15
# VS Version: 1.19.3
Next Steps
