How to Install Mods on a Factorio Server (mod-list.json Guide)

To install mods on a Factorio server, stop it, upload the mod .zip files (do not unzip them) into the server's mods folder, make sure each mod is enabled in mods/mod-list.json, and start it again. Copy your mod-settings.dat across too if you changed any mod startup settings. Players install nothing by hand: when they join, Factorio sees the server's mod list and offers to download the exact same mods and versions from the mod portal.

Short answer

1. Set up the mods in your own game first, start a test map, and make sure it loads.
2. Stop the server and take a backup.
3. Copy the mod zips from your own mods folder into the server's mods folder.
4. Copy your mod-list.json and mod-settings.dat as well.
5. Start the server, and use a new save or one created with those mods.
6. Players connect and accept the mod sync.

Where are Factorio mods stored?

On your own PC, mods live in the mods folder of Factorio's user data directory:

On a headless server unpacked from the zip or tarball, the mods folder sits inside the server folder, next to bin, data and saves. On GamezServers it is the mods folder in the Files tab.

Inside you will find:

• ModName_1.2.3.zip: one file per mod, named with its version. Keep them zipped. Factorio reads the zips directly.
• mod-list.json: which mods are enabled.
• mod-settings.dat: your mod settings, in a binary format.

Step 1: Build the mod list in your own game

This saves the most time. In Factorio, open Mods, then Install, search the portal, and install what you want. Required dependencies install with them. Enable everything, start a new map, and check it loads without errors.

If your group uses a modpack someone shared as a save, use Load game, select the save, and click Sync mods with save. Factorio downloads and enables exactly the mods that save used.

Step 2: Upload the mods to the server

On GamezServers:

1. Click Save game, then Backup.
2. Stop the server.
3. In the Files tab, open mods and upload the mod zips from your PC. For big lists, use SFTP: Settings, Show SFTP login, then FileZilla or WinSCP.
4. Upload your mod-list.json and mod-settings.dat over the server's copies.
5. Start the server and watch the Console. Each mod is listed as it loads.

Self hosted: copy the same files into the headless server's mods folder, or point the server at another folder with --mod-directory /path/to/mods.

Do not upload mods for a different Factorio version. A mod built for 1.1 will not load on 2.0, and the server stops with an error naming the mod.

How does mod-list.json work?

mod-list.json lists mods by their internal name and switches each one on or off:

{
  "mods": [
    { "name": "base", "enabled": true },
    { "name": "elevated-rails", "enabled": true },
    { "name": "quality", "enabled": true },
    { "name": "space-age", "enabled": true },
    { "name": "some-portal-mod", "enabled": true },
    { "name": "another-mod", "enabled": false }
  ]
}

• base must stay enabled. It is the game itself.
• space-age, quality and elevated-rails are the Space Age expansion. Every player needs the expansion if they are on. See Factorio Space Age multiplayer server.
• A zip in the folder that is missing from the list loads as enabled the first time. Set it to false to keep the file but turn it off.
• Use the internal name from the mod's info, which is the part of the zip name before the version.

Keep the JSON valid. One missing comma and the server ignores the file or refuses to start.

mod-settings.dat: startup settings must match

Factorio mods have three kinds of settings:

• Startup: set before the game loads, like recipe difficulty in an overhaul mod. They must be the same for every player on the server.
• Map (runtime global): stored in the save. On a server, only admins can change them, in game under Settings, Mod settings, Map.
• Per player: each player sets their own.

Startup settings are saved in mod-settings.dat, not in the save. If you tweaked any startup setting on your PC, upload your mod-settings.dat to the server's mods folder, otherwise the server runs with defaults that differ from the map you tested. Current Factorio versions apply the server's startup settings to a joining player as part of the mod sync. If a player still gets a settings mismatch, copying the server's mod-settings.dat into their own mods folder fixes it.

How do players get the mods?

They do not need to do anything first. When a player connects:

1. Factorio compares their mods with the server's.
2. If anything differs, it shows the list and offers to download and enable the missing mods at the right versions from the mod portal.
3. They confirm, Factorio restarts, and they join.

Downloading from the portal needs the player to be logged in to a factorio.com account in game (Steam copies can sign in through Steam). It only works for mods on the official portal. A private mod or an edited zip cannot sync this way, so every player has to get that exact file from you by hand. That is a good reason to stick to portal mods on shared servers.

Updating mods

When a mod updates on the portal, nothing changes on the server until you update it. That is good: players keep joining with the server's version thanks to the sync. To update:

1. Update the mods in your own game.
2. Stop the server, back up, delete the old zips and upload the new ones.
3. Start the server. Players get the new versions on their next join.

Read the changelog for big overhaul mods first. Some updates break existing saves.

Adding or removing mods on an existing map

• Adding a mod to a running map works for most quality of life mods. Content mods like big overhauls often expect a fresh map.
• Removing a mod deletes everything it added from the map: its buildings, items and recipes. Back up first.

Factorio shows a migration message when you load a save with a changed mod list. Read it before you play on.

Common problems

• Server will not start after adding mods: a mod is for the wrong Factorio version or is missing a dependency. The console names it.
• "Mod mismatch" and the sync fails: the mod is not on the portal, or the player is not logged in to factorio.com.
• Mods load but the map is vanilla: the server is running an old save made without them. Create a new map, or upload the save you made with the mods.
• Settings mismatch on join: the player's startup settings differ. Share the server's mod-settings.dat.
• Version mismatch: server and players on different Factorio versions. See Factorio version mismatch fix.

The easy way

On a GamezServers Factorio server you upload your mods folder in the file manager, back up with one click before every change, and keep the server on the version your group plays with Update game. Players sync the rest themselves. If your modded save already exists, also see how to upload a Factorio save to a server.

FAQ

Do I unzip Factorio mods for the server?

No. Upload the zip files as they are. Factorio loads mods straight from the zips in the mods folder.

Can the headless server download mods itself?

Partly. The --sync-mods option syncs the mods folder with a save, and on a headless server it needs your factorio.com username and token. Most people find it simpler to upload the zips from their own game.

Do I need to restart the server after adding mods?

Yes. Factorio only loads mods at startup. Stop the server, add the files, then start it again.

Can I use different client side mods than the server?

No. Every mod in Factorio is loaded on every machine, so the mod list must match exactly. Factorio enforces this when you join.

How many mods can a Factorio server run?

There is no fixed limit. Big overhaul packs mainly cost RAM and start time, so move to the 8 GB plan for large mod lists.