How to Install Mods on a Factorio Server

Why Factorio is strict about server mods

Factorio multiplayer uses a lockstep design. The server and every connected player run a full simulation of the whole factory, and only player actions travel across the network. That keeps traffic small even on a huge base, but it only works if every copy of the game would calculate exactly the same result from the same inputs. One extra mod, a different mod version or a different startup setting means the simulations would drift apart, so Factorio refuses the connection rather than letting the game desync.

That is why the official multiplayer documentation says every game instance needs exactly the same game version and mods, and why Factorio calculates a checksum for each mod at startup and compares it with the server when someone joins. It is not being fussy. It is protecting the factory.

The good news is that Factorio makes the player side easy. When someone joins a modded server, the game offers to synchronise their mods with it. Accepting downloads and enables every mod the server uses, at the exact versions the server runs, and can bring the mod startup settings across too. So your job as the server owner is mainly to get the server’s own mods folder right. Players follow it.

Before you install anything

1. Check the game version. Each mod declares one major Factorio version in its info.json as factorio_version, such as 2.0. A mod is only compatible with that major version and no other, even if its code would otherwise work. A mod built for 1.1 will not load on a 2.0 server, so filter the mod portal by the version your server runs.
2. Back up the save. Stop the server cleanly so it writes its latest save, then download a copy. Our guide to uploading, backing up and transferring Factorio saves covers where the files live and how to restore one.
3. Decide whether this is a new world or an existing one. Big overhaul mods change map generation and the tech tree, so they usually belong on a fresh map. Quality-of-life mods can normally join a running save, but they still rewrite it once they load.
4. Know how you reach the server’s files. On a rented server that is the panel’s file manager or FTP/SFTP. On your own machine it is the user data directory, or a folder you point the server at with --mod-directory.

The three files that make up a server’s mod setup

Almost every server mod problem comes down to one of three things in the mods folder. It helps to know what each one does before you start copying files around.

Method 1: build the mod list in your game, then copy it to the server

This is the quickest way that also avoids most startup errors, because Factorio’s in-game mod browser does the awkward parts for you. It downloads required dependencies automatically, warns about incompatible mods and lets you set startup settings in a normal menu instead of a binary file.

1. Start Factorio on your PC at the same version as the server and open Mods from the main menu.
2. Install the mods you want from the in-game mod portal and enable them. Required dependencies come down with them.
3. Open Settings → Mod settings and set the Startup tab the way you want the server to run. Values on the Map tab can be changed later by an admin in game.
4. Start a quick single-player map to confirm the game loads with that list without errors, then quit.
5. Find your local user data directory: %appdata%\Factorio on Windows, ~/Library/Application Support/factorio on macOS, or ~/.factorio on Linux. Open its mods folder.
6. Stop the server. Upload the mod zips you want, plus mod-list.json and mod-settings.dat, into the server’s mods folder.
7. Start the server and read the console or log until the save loads. Then join from your own game. If everything matches, you go straight in without a sync prompt.

Copy only the mods the server needs. A client-only helper sitting in your local folder becomes part of the server’s list if you upload it, and then every player has to download it too. If your local mod-list.json mentions mods you did not upload, either upload them or set them to false on the server so it is not looking for files that are not there.

Method 2: upload zips from the mod portal

If you only want to add one or two mods, you can skip the local game entirely.

1. Sign in to the official Factorio mod portal with your Factorio account, open the mod’s page and download the release that matches the server’s game version.
2. Check the mod’s dependency list. A dependency with no prefix is required, so download that mod too. ? marks an optional dependency, + a recommended one, (?) a hidden optional one and ~ one that does not affect load order. ! means the two mods are incompatible and must not be enabled together.
3. Stop the server, connect with the panel file manager or FTP, open mods and upload every zip unchanged.
4. If the server already has a mod-list.json, make sure each new mod is listed with "enabled": true, or delete its entry and let the game add it.
5. Start the server and check the log before inviting anyone.

This method leaves every startup setting at its default. That is fine for many mods. If you want something different, set it in your own game and upload your mod-settings.dat as in method 1.

Method 3: let a headless server fetch mods for a save

If you run your own headless server and already have a modded save, Factorio can read the mod list from the save itself. Launch the server with --sync-mods and the save file, and it syncs its mods to match that save. To download anything missing, the headless server needs your Factorio account details as service-username and service-token in its player-data.json. The token is on your profile at factorio.com.

Treat the token like a password. It lets the server download mods as you, so keep it off shared screenshots and out of any config you post for help.

The widely used factoriotools Docker image has its own switch for this: setting UPDATE_MODS_ON_START to true updates mods every time the container starts, using a Factorio username and token, and UPDATE_IGNORE takes a comma-separated list of mods to leave alone. It skips the Space Age mods space-age, quality and elevated-rails on purpose, because they ship with the game and are not downloaded separately.

Mod settings: which ones the server controls

Factorio mods can define three kinds of setting, and they behave very differently on a server. Mixing them up is the reason many people think their server “ignored” a setting.

• Startup settings are applied while the game builds its prototypes, before any map loads. They cannot change while the game is running and must have the same value for every player on the server. On a dedicated server they come from mod-settings.dat, so change them in your game, upload the file with the server stopped and start it again.
• Map settings (called runtime-global in the modding API) belong to the save and can be changed while it runs. On a server, only admins can change them, in game through Settings → Mod settings → Map.
• Per player settings (runtime-per-user) are each player’s own. When someone joins, their own “keep mod settings per save” option decides whether their local values are applied or the save’s values are used.

Changing a startup setting counts as a change of mod configuration, just like adding or removing a mod. The save runs every mod’s configuration-changed step the next time it loads, which is another reason to keep a backup from before the edit.

Adding mods to a world that already exists

You can add mods to a running world, but it helps to know what happens on the first load. When a mod joins an existing save, all of that mod’s migration scripts run on it, and each save remembers which migrations it has already had so they never run twice. Every active mod also gets told that the mod configuration changed, so it can fix up its own data.

Most quality-of-life mods are built for exactly this. Mods that reshape ore generation, biters or the tech tree are a different matter. The existing map will not regenerate around them, so you can end up with an odd mix of old terrain and new rules. If a mod’s description recommends a new game, believe it and start a fresh map with that mod list.

Add one mod at a time if you can. If the server then refuses to start, you know exactly which change caused it.

Updating mods without locking players out

Mod updates are where most “players cannot join” reports start, because the server and the players can easily end up on different versions after a patch.

1. Stop the server cleanly and back up the save.
2. Upload the new version’s zip and delete the old zip for that mod, so the folder holds one version of each mod and there is no doubt which one loads.
3. Check the new version’s dependencies. Updates sometimes need a newer version of a library mod as well.
4. Start the server and confirm the save loads.
5. Tell players to join normally and accept the sync prompt. The game downloads the exact version the server now runs.

Do the same after a Factorio update. A new major version can leave mods behind until their authors release a matching build, so check your mod list on the portal before moving a modded server to a new game version.

Removing a mod safely

Removing a mod is the step that can cost you progress. Factorio cannot keep things in a save that no longer exist in the game, so anything that only came from that mod, such as its buildings, items, recipes and research, is removed when the world loads without it. Ghosts of its buildings can disappear as well.

• Make a copy of the save first and keep it until you are sure.
• Load the save once without the mod and walk the base. If something important vanished, restore the copy.
• Remove the mod’s dependents first. A mod that requires the one you are removing will stop loading as well.
• To pause a mod rather than delete it, set it to "enabled": false in mod-list.json. The effect on the save is the same as removing it, but the zip stays ready to switch back on.

Turning Space Age and other built-in mods on or off

Factorio 2.0’s Space Age expansion arrives as built-in mods rather than a separate download. They show up in mod-list.json as space-age, quality and elevated-rails, alongside base. To run a server without the expansion, stop it, set those entries to false and start it again. To run the expansion, set them to true. A typical file looks like this:

{
  "mods": [
    { "name": "base", "enabled": true },
    { "name": "elevated-rails", "enabled": true },
    { "name": "quality", "enabled": true },
    { "name": "space-age", "enabled": true },
    { "name": "better-armor", "enabled": true }
  ]
}

Players need the same choice on their side. Someone without the expansion cannot join a Space Age server, and loading a Space Age save with those mods switched off strips the expansion’s content out of it, exactly like removing any other mod. Pick before the first map is generated if you can, because switching later is the same kind of change as adding or removing any other mod.

Fixing common Factorio server mod errors

Mods also add work for the server. Each one can add script time to every tick, and big overhauls add whole new systems to simulate. If the server holds 60 UPS on vanilla but slows down once a pack is installed, our Factorio server requirements guide explains how to read the time-usage overlay and size RAM and CPU for a modded factory.

If you would rather have a panel that lets you upload mods and edit mod-list.json in a browser, compare plans in our best Factorio server hosting guide.

Factorio server mods FAQ

Do I need to unzip Factorio mods before uploading them to a server?

No. Factorio installs mods by copying the .zip into the mods folder exactly as you downloaded it. The zip name has to contain the mod name and version, so do not rename it either.

Do players need to install the same mods themselves?

They need the same mods at the same versions, but they do not have to find them by hand. When they join a modded server, Factorio offers to sync their mods with it and downloads the exact versions the server runs. Startup settings can be synced at the same time.

How do I change startup mod settings on a dedicated server?

Set them in your own game under Settings, Mod settings, Startup, then stop the server and upload your mod-settings.dat into its mods folder. Startup settings must be the same for everyone and cannot change while the game is running, so a restart is always part of the change.

Can I add mods to an existing Factorio save?

Yes. The mod’s migrations run on the save the first time it loads with that mod, and most quality-of-life mods are fine. Overhaul mods that change map generation or the tech tree are better started on a new map. Back up the save first either way.

What happens to my factory if I remove a mod?

Anything that only existed in that mod is removed from the save when it loads without it, including its buildings and items. Copy the save first, load it once without the mod and check the base before you commit to the change.

More Factorio server guides

Our Factorio host comparison, plus the requirements and save guides that sit alongside this mods walkthrough.