How to add mods to a Factorio server

Factorio mods come from Wube’s own mod portal at mods.factorio.com. On your server, install them from the Mods tab in one tap. Friends don’t need to set anything up first: when they join, the game offers to download the same mods for them.

Before you install: add your token

The mod portal only gives mod files to signed-in Factorio owners. So the Mods tab needs your factorio.com username and token, which you add once in Settings. Add your factorio.com token shows where to find it.

Without a token you can still upload mods by hand, as shown below.

Install mods from the Mods tab

1. Open your server in the panel and go to Mods.
2. Search for a mod by name. Results are marked when they don’t fit your game version.
3. Tap install. The panel shows what it will add, including the mods it depends on.
4. Confirm. We make a backup first, then download the mod straight from the mod portal.
5. Restart the server when the panel asks, so the mod turns on.

You can install mods while the server sleeps. They turn on the next time it starts.

Mods never update on their own, because updates can break saves. When an update is out, the Mods tab shows it with its changelog. Update when your group is ready, since everyone will need the new version.

What your friends need

Nothing, before they join. When a friend connects to a server with different mods, the game shows Mods mismatch detected! with a list, and offers Sync mods with server.

1. Select Sync mods with server.
2. Make sure Sync startup settings is ticked, so their mod settings match yours.
3. The game downloads the mods, turns them on and restarts.
4. It then joins the server.

Friends need to be signed in to factorio.com in the game for the download. Steam players usually are already.

A mod that isn’t on the mod portal can’t be synced. Friends have to install it by hand, the same way you did.

Install mods by hand

Use this for a mod that isn’t on the portal, or if you’d rather not add your token.

1. Download the mod’s .zip file. Don’t unzip it.
2. Stop the server from Overview.
3. Upload the .zip to the mods/ folder in Files, or over SFTP.
4. Upload every mod it depends on, too. The mod’s page lists them.
5. Turn the mod on in mods/mod-list.json. Each mod has an entry like this:

{
  "mods": [
    { "name": "base", "enabled": true },
    { "name": "your-mod-name", "enabled": true }
  ]
}

6. Start the server from Overview.

The name in mod-list.json is the mod’s internal name from its portal page, not its title.

Space Age and the built-in mods

Space Age isn’t a normal mod download. It’s part of the game, made of built-in mods that come with your server:

• space-age
• quality
• elevated-rails
• recycler

Don’t delete or turn these off by hand. Switch between vanilla and Space Age with the server type in Settings instead. We make a backup first.

A save made with Space Age needs Space Age to load. A vanilla save can load in Space Age, but the game warns that a new map is the better way to play it.

Some mods only work with Space Age. On a vanilla server the game won’t start them and says the mod requires the Space Age expansion.

Mod settings

Factorio mods have two kinds of settings:

• Startup settings live in mods/mod-settings.dat. Change them in your own game, then upload that file to the server’s mods/ folder while it’s stopped. Friends get them through Sync startup settings.
• Map settings live in the save. Admins change them in game, under Settings > Mod settings.

Game updates and mods

Every player and the server need the same game version and the same mod versions. After a big Factorio update, some mods need an update from their author before they load.

• Before a big update, pin your game version in Settings if your group relies on a mod that might break.
• Unpin it once your mods show the new version on the mod portal.
• Update the mods from Mods. Friends get the new versions the next time they sync.

If the server won’t start after a mod change

1. Open the Console. If the crash helper recognises the problem, follow its fix.
2. Remove the mod you added or updated last from Mods, then start again.
3. Still stuck? Restore the backup we made before the change, from Backups.

More fixes are in Fix common Factorio server errors.