How do I install mods on my Valheim server?

Caution

To join a modded server, every player must install matching mods on their game client. The panel only installs files on the dedicated server.

Valheim mods use BepInEx. On AleForge you switch the server to Valheim BepInEx with Game Swap, then install packages from Thunderstore in Mod Manager. After swapping, the latest version of BepInEx will be installed on your server.

Switch to Valheim BepInEx with Game Swap

Vanilla Valheim cannot load BepInEx plugins. If you are already on a Valheim BepInEx instance, skip this section.

1. Go to the [AleForge Panel](https://panel.aleforge.net/)
2. Stop the server
3. Open `Backups` and create a backup
4. Open `Game Swap`
5. On an empty slot, click `New Game`
6. Search `Valheim` and select the Valheim template
7. Under `Server Version / Type`, choose `Valheim BepInEx`
8. Leave `Backup Active Server` checked so the current instance is stored in that slot
9. Click `Confirm Action` and wait for the install to finish

Caution

The new BepInEx instance starts a new world. Backup Active Server keeps your previous instance in a Game Swap slot. It does not copy that world onto BepInEx. To keep playing the same map, restore it after the swap and set World Name on Startup to match. See How do I upload my Valheim world?.

When the swap finishes, install mods next, then start the server.

Install mods with Mod Manager

Mod Manager is in the server sidebar. It browses the Thunderstore Valheim catalog.

1. Open your Valheim BepInEx server in the [AleForge Panel](https://panel.aleforge.net/)
2. Click `Mod Manager` in the sidebar
3. Stay on `Mods`, or switch to `Modpacks`
4. Search, sort by `Most Popular`, `Last Updated`, or `Newest`
5. Leave `Hide client-side` checked unless you know you need a client-only package
6. Click `Install` on a mod, or `Install pack` then `Confirm install` on a modpack
7. Wait for the progress bar to finish
8. Restart the server so the plugins load

Mods do not hot-load. Restart after every install, uninstall, or update.

Dependencies install automatically. Already-installed packages show as Installed. BepInEx itself cannot be uninstalled from this page.

Modpacks

The Modpacks tab is a separate Thunderstore list. Installing a pack asks for confirmation. Optional: check Replace existing plugins to clear /BepInEx/plugins before the pack (this does not remove BepInEx).

Installed and uninstall

Installed lists packages that Mod Manager placed on the server. Click Uninstall, then Confirm. Manual zips you dropped into BepInEx/plugins through Files will not appear here.

Updates

Open Updates, click Check for Updates, then Install all updates if anything is behind. Restart (or Start server if it is offline) when the panel asks.

Client mods

Players still need the same Thunderstore packages on their PCs. Install BepInExPack Valheim locally, then the same mods you installed on the server. A Thunderstore client such as r2modman or Gale is the usual way to do that.

Manual upload (optional)

Use this only if a package is not on Thunderstore or you already have a zip.

Caution

If the zip is larger than 1 GB, upload using SFTP.

1. Stop the server
2. Open `Files`
3. Go to `BepInEx/plugins`
4. Upload the zip and `Unarchive` it
5. Start the server

Manual uploads do not show under Installed or Updates in Mod Manager.

If install fails

If Mod Manager says the server is missing BepInEx Doorstop files, Game Swap to a new Valheim instance and set Server Version / Type to Valheim BepInEx. Do not change the startup command by hand to force BepInEx.

For world files after a swap, use upload a Valheim world and backup and restore.