How to Install Mods on a Terraria Server
Vanilla Terraria servers cannot load mods, so a modded server means moving the whole group to tModLoader. Here is how to make that switch, build a mod pack the server can install, keep every player on the same version, and get past the startup and join errors that stop most modded worlds.
A vanilla client cannot join a tModLoader server, and tModLoader will not connect to a non-tModLoader server. Treat them as two different games sharing a name.
install.txt tells the server which Workshop mods to fetch, and enabled.json tells it which of those to enable. Build those on your own PC first.
A modded world is not just .wld. Keep the matching .twld beside it or modded tiles and items disappear.
Exact tModLoader version match matters, mod versions matter, and one bad mod can cause disabled mods, endless Connecting, or startup crashes.
Vanilla to tModLoader: what actually changes
The big mistake is assuming a vanilla Terraria server can be “upgraded” into a modded one by dropping files into it. It cannot. Vanilla Terraria does not load content mods at all. Calamity, Thorium and similar packs need tModLoader, which is a separate Steam app installed alongside Terraria. That is why switching a server to modded play is not just a mod upload job; it is a change of server software, save location and client requirement.
This also explains the current version problem. Vanilla Terraria is on 1.4.5, but stable tModLoader is still built on Terraria 1.4.4. There is a 1.4.5-dev branch for contributors, not for a normal friend group, and there is no release date for a stable 1.4.5 tModLoader. If you saved your existing vanilla world in 1.4.5, stable tModLoader will show (LaterVersion) and refuse to open it. Start a fresh modded playthrough in tModLoader, or use an older pre-1.4.5 copy if you still have one.
| Feature | Vanilla server | tModLoader server |
|---|---|---|
| Who can join | Vanilla Terraria clients | Only tModLoader clients on the exact same tModLoader version |
| Content mods | No | Yes |
| World files | Uses vanilla world data | Uses .wld plus matching .twld mod data |
| Save folder | Terraria save folder | Separate tModLoader save folder |
tModLoader keeps saves separate from vanilla, which is useful because it stops modded and unmodded worlds trampling each other. On Windows the default tModLoader save folder is %UserProfile%\Documents\My Games\Terraria\tModLoader; on Linux it is ~/.local/share/Terraria/tModLoader/; on macOS it is ~/Library/Application support/Terraria/tModLoader/. The Migrate individual players... button can copy vanilla players and worlds into tModLoader, but only if those saves are not too new. If you only need admin tools and a plain server, not content mods, stick with vanilla and follow our guide to setting up a vanilla Terraria dedicated server.
TShock is separate again. It is a vanilla server package aimed at plugins and administration, not content mods. A server runs tModLoader or TShock, not both.
Build and test the mod list on your own PC first
Your own tModLoader install should be the workshop bench for the server. Download the mods from Workshop, enable them, let tModLoader reload, and start a small test world before you touch the live server. That catches missing dependencies, broken mods and obvious memory blow-ups locally, where the cost is just your own time rather than a whole group waiting at a join screen.
- Install and open tModLoader on your PC.
- Use
Workshop > Download Modsor subscribe through the tModLoader Steam Workshop. - Enable the mods in
Workshop > Manage Mods. - Reload, then start a test world and make sure it actually loads.
- Go to
Workshop > Mod Packsand chooseSave Enabled as New Mod Pack. - Use
Open Mod Pack Folderand keep that pack as the master copy for the server.
The important files are in that pack’s Mods folder. install.txt contains the Steam Workshop publish IDs for the mods, because the Workshop identifies them by ID rather than by display name. enabled.json is the list of mods that should be switched on. Those do different jobs: one fetches, the other enables. If install.txt is missing, nothing gets installed from Workshop. If enabled.json is missing, the server can have mods sitting on disk and still start with none of them enabled.
If you use manually installed .tmod files, copy those as well. Local .tmod files live in the Mods folder, show purple in the mods menu, and do not auto-update. They still need to be present on the server, and enabled.json still needs to include them.
A mod pack is better than a mod collection for a server because a pack is a frozen snapshot. A collection always pulls the latest version, which is the opposite of what you want when you are trying to keep a group aligned across monthly tModLoader updates. If you want the loader version captured too, Export Pack Instance also writes a tmlversion.txt file.
Use this flow as the basic pipeline for every update, not just the first install:
How mods reach players on join
tModLoader does not treat every mod the same. Each mod author sets a ModSide, which controls whether the server needs the mod, whether it is sent to joining players, and whether a player can keep it enabled if the server does not have it. This is why some mods seem to “just sync”, while others are purely personal client extras.
In plain words: Both is the usual setting for content mods, so the server loads it and sends it to missing players on join. Client is for things like UI, keybinds, textures or music, so the server does not need it and it is never required. Server runs only on the server and is not sent to players. NoSync means optional on both sides and not downloaded on join.
This is good news for the server owner. Get the content mods right on the server and players who are missing one receive it when they join, so you do not need to send everyone a download list. Client-only mods do not belong on the server at all, and every extra content mod you load there costs startup time and memory.
The matrix below is the quick rule set to use when deciding what the server must carry:
| Mod side | Server must have it | Sent to players on join | Stays on if the server lacks it |
|---|---|---|---|
| Both (most content mods) | Yes | Yes | No |
| Client (UI, textures, music) | No | No | Yes |
| Server (server-only tools) | Yes | No | Not used |
| NoSync (optional both sides) | No | No | Yes |
Install mods on a rented Terraria server
On a rented server, the first job is not uploading mods. It is switching the server type or version to tModLoader in the host panel. Until that changes, the host is still launching vanilla Terraria binaries, which cannot load the mod files no matter where you upload them. If your current plan only handles vanilla or hides the tModLoader folders, look for modded Terraria hosting rather than a vanilla-only Terraria slot.
- Switch the server software to tModLoader. This is what changes the executable, save folder layout and startup behaviour.
- Back up the current world, or start fresh. A vanilla 1.4.5 world will not open in stable tModLoader, so do not overwrite your only copy while testing.
- Upload the mod pack files. If the panel has Workshop integration, use it. If not, upload to the server’s
tModLoader/Modsfolder by FTP or SFTP. - Include the right files. Workshop-based installs need
install.txtandenabled.json. Manual mods need the actual.tmodfiles as well, plus entries inenabled.json. - Upload the world properly. Keep
WorldName.wldandWorldName.twldtogether in theWorldsfolder. Point the server at the.wldfile, never the.twld.
If the host uses a non-default path for mods, set modpath= so the server knows where to read the .tmod files. That setting matters because tModLoader can only enable what it can actually find on disk. After the restart, watch the console or server.log. You want to see the server loading mods before it starts the world. If it reaches the world with no mod loading stage, the usual causes are missing install.txt, missing enabled.json, or the wrong modpath.
Install mods on a self-hosted Windows server
On Windows, start the server from start-tModLoaderServer.bat inside the tModLoader install folder. The script asks whether to enable Steam support, then which world to use, max players, port forwarding and password. For one-off setups that is fine, but a saved serverconfig.txt is better for repeatable restarts because it stops a prompt being answered differently by mistake.
world=C:\Users\YOU\Documents\My Games\Terraria\tModLoader\Worlds\WorldName.wld maxplayers=8 port=7777 password=YourPassword modpack=MyModpack
Use world= first. Many settings such as port and max players are ignored unless a world is specified. maxplayers accepts 1 to 255. modpack= takes the pack’s name without the .json extension and makes the server load only the mods in that pack, instead of whatever is still enabled from old tests. Add modpath= only if you keep manually installed .tmod files outside the default Mods folder.
For headless startup, use -nosteam or -steam -lobby friends / -steam -lobby private, plus -world with the full path to the .wld file if you are not relying on serverconfig.txt. On Windows, the firewall must allow the tModLoader server’s dotnet.exe entries. Terraria and tModLoader default to TCP port 7777, so friends outside your house also need that port forwarded to the PC running the server. A 192.168.x.x address is only a local address; it will not work for internet players.
Install mods on a Linux server
For Linux, the clean routes are the official Docker setup or the manage-tModLoaderServer.sh script. Both exist for the same reason: repeatable installs and updates. A modded server is not just one binary; it is the loader version, the mods, the enabled state, the world files and, sometimes, a pinned release. Automating that reduces human error.
./manage-tModLoaderServer.sh install-tml --username your_steam_username ./manage-tModLoaderServer.sh install-mods ./manage-tModLoaderServer.sh start # or do both install steps and updates together ./manage-tModLoaderServer.sh install
tModLoader/
Mods/
enabled.json
install.txt
*.tmod
Worlds/
WorldName.wld
WorldName.twld
serverconfig.txt
tmlversion.txt The server and steamapps folders are created automatically. Keep enabled.json and install.txt in tModLoader/Mods, not beside it. If you need a specific tModLoader release, pin it with tmlversion.txt from an exported pack or set the matching environment variable in Docker. That pin matters because monthly stable updates can move faster than your chosen mod set. Also note that tModLoader and its dedicated server do not run on ARM.
Keep versions matched and stop monthly updates breaking the group
The error You are not using the same version as this server is literal. The client and server tModLoader versions must match exactly. Then the mod versions need to match as well. Because tModLoader pushes stable updates every month, a setup that worked yesterday can break today simply because one machine updated and another did not.
Do not use the 1.4.5-dev branch as a shortcut around this. It exists for development work, not stable group play. Stable 1.4.4 tModLoader keeps receiving monthly updates, and 1.4.4 will remain available as a legacy version after 1.4.5 arrives, which is useful if a long-running pack needs to stay put. Calamity is a good example: its team announced on 10 August 2026 that it was ending further development, and the current release works on the tModLoader version it supports. A frozen pack plus a pinned loader version is how you keep a world like that playable.
- Back up first. Copy the world’s
.wldand.twld, and keep the current mod pack files. tModLoader also keeps dated zip backups insideWorlds\BackupsandPlayers\Backups. - Update the server’s tModLoader and mods together. Do not update one and leave the other for later.
- Tell every player to update before the next session. One out-of-date client is enough to block that player.
- Test one join before the whole group logs in. That confirms version sync, mod sync and world loading while the problem surface is still small.
The timeline below is the safe way to handle those monthly changes:
before anything changes
on the server first
update tModLoader
modded items and NPCs
- Read server.log in tModLoader-Logs
- Disable that mod until its author catches up
Mod configs, save files and memory limits
Many mods write their settings into the ModConfigs folder inside the tModLoader save directory after they have loaded once. Stop the server before editing those files, then start it again so the mod reads the new values. On many hosted Linux setups the path is /.local/share/Terraria/tModLoader/ModConfigs.
The memory side is where most large packs go wrong. Content mods add to the memory the server holds from startup onwards, so OutOfMemoryException is usually not a network issue at all; it means the loaded set is too heavy for the available RAM. Large content mods are the main culprit. Reducing the number of big mods, or choosing a smaller world, cuts what has to stay resident in memory.
tModLoader can show where that memory is going. In Settings > tModLoader Settings, turn on Show Mod Memory Estimates, restart, and check the per-mod graph in the mods menu. That helps you identify the expensive part of a pack instead of guessing. For planning, our comparison guidance puts tModLoader servers at a 3-4GB minimum, compared with 512MB-1GB for a small vanilla group, and tModLoader lists 6 GB RAM as the minimum system requirement for playing on the client side. For the wider CPU and memory picture, see our guide to game server hardware requirements.
Common startup and join problems
When a friend cannot join, do not change six things at once. Check the server type, the exact tModLoader version, the world files, then the mod pack files. If there is still no answer, read logs: client.log and server.log live in the tModLoader-Logs folder of the install folder, and multiplayer-only errors often need both sides to make sense.
This flowchart is the quickest way to narrow down where the failure lives:
| Symptom | Likely cause | First fix |
|---|---|---|
| You are not using the same version as this server | Client and server tModLoader versions do not match exactly, or a vanilla server is still bound to the same port | Confirm the server is actually running tModLoader, not vanilla, and update every player to the exact same tModLoader version; also make sure no vanilla server is running on 7777 |
World shows (LaterVersion) | The world was saved in a newer Terraria version than the stable tModLoader build supports | Use an older compatible copy if you have one, or start a new tModLoader world; a vanilla 1.4.5 world will not load in stable 1.4.4 tModLoader |
| Mods get disabled when joining | A bad mod is throwing errors during join | Read server.log, remove or stop using the mod that errors, then test again |
| Stuck on Connecting… | Usually a mod problem during sync or world load | Try a fresh player and world, then start the server with no mods and add a few at a time until it breaks; compare client.log and server.log |
OutOfMemoryException on start | Not enough RAM for the loaded mod set, often due to large content mods | Cut the big mods first, consider a smaller world, then use Show Mod Memory Estimates to see what is consuming memory |
| Server starts with no mods | Missing install.txt, missing enabled.json, or wrong modpath | Put the files in the server’s Mods folder, verify modpath= if used, and restart |
Can’t connect at all on 7777 | Firewall, missing port forward, or trying to use a LAN address over the internet | Allow the tModLoader dotnet.exe through Windows Firewall, forward TCP 7777, and do not give outside players a 192.168.x.x address |
| World loaded but modded items are gone | The matching .twld file is missing | Restore the .twld that belongs with that .wld, and make sure the server points at the .wld file only |
| A mod broke after an update | Monthly tModLoader update or mod update introduced an incompatibility | Restore the last working backup or pin the known-good loader version with tmlversion.txt, then update the whole group together later |
Tune it, stay self-hosted, or upgrade
Before spending more, decide which problem you are actually solving. Some issues are resource limits, but many are just version discipline and file layout. If you are comparing always-on uptime, file access, version pinning and tModLoader-friendly panels, our Terraria server hosting comparison is the quickest shortlist.
| Situation | Best move | Why |
|---|---|---|
| Small mod list, private sessions, the host PC is on when you play | Stay self-hosted | Lower admin overhead and easier local testing; version control matters more than infrastructure here |
| Large content pack such as Calamity or Thorium plus extras | Prioritise RAM headroom and a clean mod pack workflow | Big content mods are the main memory cost, so stable pack files and enough memory matter more than fancy extras |
| More players, longer sessions, server should stay online when the host PC is off | Use a rented tModLoader server | That solves uptime and centralises the world, logs and updates in one place |
| The group keeps breaking after monthly updates | Pin versions and update on a schedule | A frozen pack and one planned update window stop half the group drifting onto different builds |
| Combat feels inconsistent rather than outright crashing | Tune configuration before upgrading | Settings such as npcstream trade bandwidth against enemy update skipping; lower values use more bandwidth but can reduce skipping |
If you would rather stop fighting version selectors, file paths and limited panels, compare hosts that make mod packs, world uploads and restarts straightforward.
Compare the best Terraria server hostsTerraria server FAQ
Can you add mods to a vanilla Terraria server?
No. Vanilla Terraria cannot load content mods, so a vanilla server cannot run Calamity, Thorium or similar packs. You need to switch the server software to tModLoader and every player needs tModLoader as well.
Do my friends need the same mods to join my tModLoader server?
They need the same tModLoader version as the server, and the required server-side mods must match. For most content mods marked Both, the server can send the mod to a player on join if they are missing it. Client-only mods are different: those are personal and are not required by the server.
Why won’t my Terraria world load in tModLoader?
The usual reason is version mismatch. Stable tModLoader is still built on Terraria 1.4.4, so a world saved in vanilla 1.4.5 shows (LaterVersion) and cannot be opened there yet. Another common cause is missing the world’s matching .twld file, which strips the modded data.
How much RAM does a modded Terraria server need?
For planning, the safe floor is much higher than vanilla: tModLoader servers generally need 3-4GB minimum, while a small vanilla group can fit into 512MB-1GB. The exact pressure comes mostly from the mod list, especially large content mods. If you hit OutOfMemoryException, remove big mods first and check memory estimates before assuming the network is at fault.
Can I run tModLoader and TShock on the same server?
No. TShock is a separate vanilla server package focused on plugins and admin tools, while tModLoader is the mod loader for content mods. Pick one software stack for that server instance; they are not a combined install.
More Terraria server help
The host comparisons, plus our guides on running a Terraria server yourself.
Checked against tModLoader’s own documentation and its stable updates up to November 2026. Whatever changes in a future update, the three rules stay the same: everyone on tModLoader, versions matched exactly, and your saved mod pack as the master copy.
