> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vexiumhosting.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installing Mods

> How to install Vintage Story mods

# Installing Mods

Enhance your Vintage Story server with mods from the community.

## Best Practices

<Tip>
  **Before installing mods:**

  1. **Check RAM requirements** - Mods significantly increase memory usage
  2. **Match versions exactly** - Mods must match your VS server version
  3. **Backup first** - Always backup before adding or updating mods
  4. **Test one at a time** - Add mods individually to identify issues
  5. **Notify players** - Players need the same mods installed
  6. **Keep a mod list** - Document installed mods and versions
</Tip>

## 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+      |

Large world generation and many mods together can require even more RAM.

## Finding Mods

### Official Mod Database

The official source for Vintage Story mods:

* **[ModDB](https://mods.vintagestory.at/)** - 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

1. Visit [mods.vintagestory.at](https://mods.vintagestory.at/)
2. Find a mod compatible with your VS version
3. Download the `.zip` file

### Step 2: Upload to Server

1. Open **Files** in panel
2. Navigate to the `Mods` folder
3. Click **Upload**
4. Select the mod `.zip` file
5. Wait for upload to complete

### Step 3: Restart Server

1. Stop the server
2. Start the server
3. 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

1. Download the mod from the same source
2. Find your VS mods folder:
   * Windows: `%appdata%\Vintagestory\Mods`
   * Linux: `~/.config/Vintagestory/Mods`
   * Mac: `~/Library/Application Support/Vintagestory/Mods`
3. Place the mod `.zip` in the folder
4. Launch the game

## Mod Configuration

Many mods create config files in `/data/ModConfig/`:

1. Stop server
2. Navigate to `/data/ModConfig/`
3. Find the mod's config file
4. Edit settings
5. 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`:

```json  theme={null}
{
  "AllowAnyMod": true
}
```

### Allow Specific Mods Only

```json  theme={null}
{
  "AllowAnyMod": false,
  "AllowedMods": [
    "modname1",
    "modname2"
  ]
}
```

## Updating Mods

### Update Process

1. Download new mod version
2. Stop server
3. Delete old mod file from `/Mods`
4. Upload new mod file
5. Start server
6. Notify players to update

<Warning>
  Always backup before updating mods!
</Warning>

## Removing Mods

### Safe Removal

1. Stop server
2. Create backup
3. Delete mod from `/Mods` folder
4. Check for related config files
5. Start server

<Warning>
  Removing content mods may cause world issues if mod items/blocks exist in the world.
</Warning>

## Troubleshooting

### Mod Not Loading

**Check console for errors:**

```
[Error] Failed to load mod: ModName
```

**Common causes:**

* Wrong VS version
* Missing dependencies
* Corrupted download

### Mod Conflicts

**Symptoms:**

* Crashes on startup
* Features not working
* Strange behavior

**Solutions:**

1. Identify conflicting mods
2. Check mod compatibility notes
3. Remove one of the conflicting mods
4. 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

1. **Test mods individually** - Add one at a time
2. **Keep a mod list** - Document installed mods
3. **Regular backups** - Before adding/updating mods
4. **Check compatibility** - Before updating VS version
5. **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

* [World Settings](/games/vintage-story/world-settings)
* [Troubleshooting](/games/vintage-story/troubleshooting)


Built with [Mintlify](https://mintlify.com).