How to Install Factorio Mods on a Dedicated Server

You want mods running on your Factorio server, and you want every player to be able to join without a version argument. On a headless server that comes down to three things: the right zip files in the mods/ folder, mod versions that match your game build, and a client-side sync that Factorio handles for you once the server side is correct.

The short version

Drop mod .zip files — still zipped — into mods/ on your server, restart, and read the startup log. Players who connect are offered an automatic sync and get the exact versions you are running. The two things that break this are mods built for a different major Factorio version, and missing dependencies.

Where Mods Live on a Factorio Server

Factorio reads mods from a mods folder in its user data directory. On the headless Linux build your Factorio server runs, that is the mods/ folder at the root of your server's file tree — alongside data/, bin/ and your save file.

The official wiki is specific about the format: mods "come as ZIP files, installed by copying (not unzipping) into the 'mods' directory". Unzipping a mod is the most common way to break an install. Leave the archive intact.

The filename matters too. Wube's modding documentation states the mod zip "must be named in the pattern of {mod-name}_{version-number}, for example better-armor_0.3.6". Both parts come from the mod's info.json, so renaming a zip can stop the game loading it.

Installing Mods: Step by Step

1. Find the mod on the official mod portal. mods.factorio.com is the canonical source — where authors upload, and where previous versions are kept. Mods from the official forum's mod subforum install the same way.

2. Pick the release that matches your game version. Every release on the portal declares a factorio_version, and that field decides whether a mod loads at all — see below.

3. Download the .zip and do not extract it. You should end up with a file like even-distribution_1.0.7.zip.

4. Note the dependencies. The mod portal page lists them, and on a server this step is not optional.

5. Stop the server. Mods are read when the game loads, and files added to a running server risk being overwritten on shutdown.

6. Upload the zips to mods/ using the File Manager, dependencies included.

7. Start the server and read the log. Wube's documentation points at the log file as where errors surface — of a malformed info.json it says "the error message can be found in the log file", and the same holds for dependency and version problems. Read it before changing anything else.

8. Join and confirm. Your client will offer to sync; accept it and check the in-game mod list matches what you intended.

Build the mod list locally first

The most reliable way to produce a working set is to install the mods in your desktop Factorio client, where the in-game mod browser resolves dependencies for you, confirm the world loads, then upload the whole mods/ folder — zips and all. You get a verified-good set instead of assembling one by hand.

mod-list.json

Alongside the zips, Factorio keeps mods/mod-list.json — the game's own record of which mods are installed and which are enabled. The official wiki notes that the game adds mods to this list automatically when it finds them, and that you can edit it by hand with a text editor or from the Mods entry in the game's main menu.

The practical consequence: a mod can sit in mods/ and still be disabled. If an uploaded mod is not showing up, mod-list.json is the second place to look after the filename. Since the game writes this file itself, the safest approach is to let it — build the set locally, then upload mods/ complete with its mod-list.json.

Version Compatibility

This is where most "the mod doesn't work" tickets actually end.

Factorio releases are grouped into major versions, identified by the first two numbers. Wube's documentation spells out how it works: factorio_version is "The major Factorio version that this mod is compatible with, formatted as number.number (e.g. 2.0)", and "Mods can only be compatible with one major version, not multiple." The docs add the part that catches people out: "Even if a mod would otherwise work on a newer major release, this field needs to be updated to explicitly mark it as compatible."

So a mod marked 2.0 covers every 2.0.x release. A mod marked 1.1 does not load on a 2.0 server, regardless of whether the code would have worked.

Your server's version is set by the Factorio Version field on the Startup tab. It accepts latest, experimental, or a specific version string, and its own description warns that "This will require a full server reinstall to change." Worth knowing before you pin a version for one mod's sake. If you are unsure what latest currently resolves to, Factorio publishes the current stable and experimental headless builds at factorio.com/api/latest-releases.

Don't chase experimental builds for mods

Setting the version to experimental puts your server on a branch most mod authors have not targeted yet, and moving back is a reinstall. Stay on stable unless you have a specific reason not to.

Dependencies

Mods declare their dependencies in info.json, and Factorio enforces them. The wiki describes three kinds: a required dependency the mod cannot work without, an optional dependency that extends it, and an incompatibility — a declaration that "prevents them from being loaded together."

The dependency string format is documented by Wube as "<prefix> internal-mod-name <equality-operator> <version>", with ! marking incompatibility, ? an optional dependency, + a recommended one, and no prefix meaning required. An entry like "? some-other-mod >= 4.2.0" is an optional dependency with a minimum version.

Your server will not fetch dependencies for you

The wiki notes that "The in-game mod portal automatically downloads required dependencies when downloading any mod" — in-game. A headless server has no in-game mod browser. Every required dependency has to be uploaded to mods/ alongside the mod yourself. This is the single biggest difference between installing mods on your desktop and installing them on a server, and it is why a mod that worked fine in single-player can leave a server refusing to load.

Your server does ship with a mod-updater script, which runs as part of the installation and uses the credentials in data/server-settings.json. It is a convenience, not a substitute for uploading dependencies deliberately — treat the startup log as the authority on what actually loaded.

Mods in Multiplayer

The rule is stated plainly on the official wiki: "All game instances need the installation of exactly the same game-versions and mods." Factorio's multiplayer runs on a lock-step architecture, so there is no partial-match mode. A client with a different mod set does not get a degraded experience; it does not join.

Factorio automates the client half, though. When a player connects to a modded server, "the game will offer to synchronize the mods with the server. Confirming the mod sync will automatically download and enable all mods used by the server." Critically, "the game will download the exact same mod versions as the server is using" — not the latest versions, yours. Players need no instructions from you beyond "click yes".

It is also why changing mods mid-campaign is disruptive: every player has to re-sync, and some mods do not tolerate being removed from a save that already contains their entities.

Panel Fields You'll Actually Use

The Startup tab on your server exposes these:

Mods themselves have no Startup field — they are files, managed through the File Manager in mods/.

Common Questions

Do mods disable achievements?

Not exactly, and the distinction matters. The official wiki states that "A separate instance of achievements will be used when mods are installed and earned achievements will not register with Steam." You still earn achievements in a modded save; they land in a separate modded list instead of going to Steam.

Console commands are the stricter case. The wiki's Console page classes scripting and cheat commands as ones that "disable achievements for the save game", with the game warning you the first time you run one — worth knowing before working through Factorio console commands. The same page adds that in multiplayer, "achievements can only be earned if the player has spent more than 50% of the time online on the map where the achievement is being awarded."

Why won't my server start after adding a mod?

Read the startup log. In order of likelihood: a missing required dependency, a mod built for a different major version, an unzipped mod folder, or a renamed zip that no longer matches {mod-name}_{version}.

Can I add mods to an existing world?

Usually yes for mods that add content. Removing one from a save that already contains its entities is the risky direction. Copy your save first — autosaves are not a backup strategy.

Do players need to install anything manually?

No. They accept the sync prompt on join and Factorio downloads the server's exact mod versions for them.

Where do I get an authentication token?

From your factorio.com account; it also appears in player-data.json in your local Factorio user data directory. Treat it as a secret — it is stored in plain text in server-settings.json, and the official wiki warns that a token is sensitive information in its own right.

What to Read Next

• Factorio Console Commands: Complete List & Cheats — the admin and scripting commands, and what they cost you in achievements

---

Made with 💜 by GameServerKings