How to Run Mods on Your Terraria Server with tModLoader

tModLoader is not a plugin - it is a different server

A normal Terraria server cannot run mods. tModLoader is a standalone application, not an add-on you drop into your existing server.

Two things to get right from the start:

• Never mix vanilla and tModLoader files in the same folder. It will crash the server. Run tModLoader in a clean installation.
• Client and server must run exactly the same tModLoader version. Even when the Terraria version matches, players cannot join if the tModLoader build differs.

tModLoader is free on Steam but requires you to own Terraria.

---

Step 1 - Switch the server to tModLoader

1. Stop the server in the Potionhost control panel.
2. Go to Startup and switch to tModLoader.
3. Start the server and let it finish installing.

If you are unsure which version to pick, contact our support - a version mismatch is the most common reason players cannot get in.

---

Step 2 - Build a mod pack in the client

The easiest and most reliable way to get the right mod list onto the server is to build it in-game first:

1. Launch tModLoader on your own computer.
2. Enable exactly the mods you want to run.
3. Go to Workshop → Mod Packs and choose Save Enabled as New Mod Pack.
4. Click Open Mod Pack Folder.

That folder holds the two files you need: enabled.json and install.txt.

---

Step 3 - Put the files on the server

The server's Mods folder is usually in the root directory. Put both files there:

Mods/
├── enabled.json
├── install.txt
└── (any local .tmod files)

install.txt is the list of workshop mods the server should download itself. The format is one workshop ID per line - nothing else:

2824688072
2669644269
2563309347

enabled.json decides which mods actually load. It is a list of the mods' internal names - not display names and not workshop IDs:

[
  "CalamityMod",
  "ThoriumMod"
]

Capitalisation matters. The server runs Linux, where CalamityMod and calamitymod are two different things. It is the number one cause of Missing previously enabled mods.

If you have mods that are not on the workshop, put their .tmod files directly in the same folder. The two methods work fine side by side.

Restart the server and watch Console while it downloads and loads.

---

Step 4 - Set up serverconfig.txt

serverconfig.txt controls the world and server settings. The format is key=value, one per line:

Key	Meaning
world	Full path to the world file. Must point at the .wld - not the .twld
worldpath	The folder where worlds are stored
autocreate	Create the world if missing: 1 small, 2 medium, 3 large
worldname	World name when autocreating
seed	Seed when autocreating
difficulty	0 normal, 1 expert, 2 master, 3 journey
maxplayers	1-255
port	Default 7777
password	Password to join
motd	Welcome message
secure	1 enables extra cheat protection
npcstream	Less enemy stuttering, more bandwidth. 2-6 recommended
priority	Process priority, 0 highest to 5 lowest
modpath	Points at a different folder holding .tmod files

difficulty in this file applies at world creation. If you already have a world, changing the line does nothing.

---

Step 5 - Give players the same mod pack

The server decides the mod list, and the client has to match. A player without the same mods in the same versions is rejected.

Share the mod pack you built in Step 2 - that gives everyone exactly the same list and the same versions in one go. Players import it into their own tModLoader and enable it before joining.

The client can download workshop mods automatically on join, but it is slow, and mods that are not on the workshop are not fetched. The mod pack is the reliable route.

If your mods have custom settings, they live in the ModConfigs folder - separate from Mods, and it has to come along if you move the setup.

---

RAM and performance

Modded Terraria uses far more memory than vanilla. As a guideline:

Setup	RAM
Vanilla or a few small mods	2-3 GB
Calamity or Thorium with QoL mods	5-6 GB
Calamity with Infernum or Catalyst	6-8 GB
Very large mod packs	8 GB or more

Note that stuttering during boss fights is rarely a RAM problem - that is the simulation, meaning the CPU, doing the work. More memory will not fix it.

---

Troubleshooting

Symptom	Likely cause	Fix
You are not using the same version as this server	The player is on vanilla, or a different tModLoader build	Everyone needs the same tModLoader version
Missing previously enabled mods: X	enabled.json names a mod that is not in Mods	Check the spelling - capitalisation matters
Mods disable themselves on every restart	A mod errors during startup and is automatically removed from the list	Check server.log for the real error
It has been detected that this mod was built for tModLoader v...	The mod was built for a different tModLoader build	Download a matching release
The server finds no mods at all	An extra folder level, e.g. Mods/Mods/	Move the files up one level
The server crashes on startup	Vanilla and tModLoader files are mixed	Run a clean tModLoader installation
Players hang on "Connecting..."	Usually a badly written mod	Remove mods one at a time and test
Calamity biomes are missing from the world	The mods were installed after the world was generated	Create a new world with the mods enabled

The most important file when something goes wrong is server.log. Send it to us in a ticket if the error does not make sense.

---

Good advice

• Build the mod list in the client first. It is far quicker than editing enabled.json by hand.
• Add mods in small batches and restart in between.
• Back up Worlds/ - both .wld and .twld - before changing the mod list.
• Large mods like Calamity need a world generated with the mod enabled, otherwise parts of the content are missing.
• Avoid changing mod versions mid-playthrough if you can. Every player has to follow along at the same time.