Install & Manage Mods - Factorio Guide

Installing Mods on Factorio Servers

Mods can dramatically enhance your Factorio experience by adding new content, mechanics, quality of life features, and complete overhauls. This guide explains how to install mods on your dedicated server.

Method 1: Manual Installation (Recommended)

1. Download the mod .zip file from the Mod Portal.
2. Locate your server's /mods/ folder in the File Manager.
3. Upload the .zip file directly into this folder. Do not extract it.
4. If the mod has dependencies (requires other mods), ensure you upload those as well.
5. Restart your server. Factorio will detect and load the mods on startup.

Method 2: Client-Side Sync

This is the easiest way for your friends to join with the correct mods:

1. Ensure your server has a valid Auth Token configured.
2. When a player attempts to join, Factorio will present a "Sync mods and restart" button.
3. The game will automatically download the required files and restart with the correct settings.

Managing the Mod List

The mod-list.json file in your /mods/ directory controls which installed mods are currently active. It is a single object with one key, mods, holding an array of entries. Each entry is a name and an enabled flag, and base belongs in it like anything else:

{
  "mods": [
    { "name": "base", "enabled": true },
    { "name": "example-mod", "enabled": true },
    { "name": "another-mod", "enabled": false }
  ]
}

Set enabled to false to disable a mod without removing the file from your server. A bare object without the mods array is the most common way to break this file, and the symptom is a server that starts happily with none of your mods loaded.

The mods that are already there

Before you add anything, it is worth knowing what a stock headless install already counts as a mod, because it changes what "vanilla" means and what your mod-list.json has to say. Factorio 2.0.77 ships five, all in the game's own data/ directory:

Mod	Title	Version	Depends on
core	Core Factorio Data	ships with the build
base	Base Mod	2.0.77
elevated-rails	Elevated Rails	2.0.77	base >= 2.0.0
quality	Quality	2.0.77	base >= 2.0.0
space-age	Space Age	2.0.77	base >= 2.0.0, elevated-rails >= 2.0.0, quality >= 2.0.0

Three things follow from that table. First, Space Age is not one mod, it is three that must all be enabled together, and its own dependency line says so. Second, the Space Age planets are not separate mods: Vulcanus, Fulgora, Gleba and Aquilo are defined inside space-age, so there is nothing to enable or disable per planet. Third, their versions track the game's, so a Factorio update moves all of them at once and a pinned version of one of them is not a thing.

The difference the expansion makes is not small. With only base enabled the game resolves 217 recipes, 244 items, 196 technologies and one planet. With all four enabled it resolves 659 recipes, 333 items, 275 technologies and five planets, plus the quality ladder of normal, uncommon, rare, epic and legendary. That ladder is genuinely absent from the base game rather than merely unused: with only base enabled the game defines two quality entries, both flagged hidden, and there is nothing to promote anything to. That is why a modpack built for one will not simply run on the other.

On the 2.1 experimental line the list grows to six: recycling moved out of quality into a new recycler mod. If you keep a hand-written mod-list.json and jump to 2.1, that is the entry you will be missing.

The mod-related launch arguments

Three of the headless binary's arguments deal with mods, and they are worth knowing before you start moving zip files by hand:

• --mod-directory PATH, described by the parser as "Mod directory to use". This is how you run two servers from one install with different mod sets, instead of copying the whole game.
• --sync-mods FILE, "Sync mods with save". Point it at a save and it lines the mod folder up with what that save expects, which is the fastest fix for a save someone hands you with no mod list attached.
• --instrument-mod NAME, "Name of a mod to enable Instrument Mode", which is the hook mod authors use for profiling and debugging rather than something you need for a normal install.

Also useful when a mod is suspected of misbehaving: --check-unused-prototype-data prints a warning for every prototype value that was not accessed during load, and --verbose turns on verbose logging. Both write to the same log you would be reading anyway.

Troubleshooting

• Startup Crash: Check the factorio-current.log. This is usually due to a missing dependency or an incompatible Factorio version.
• Desynchronization: Ensure every single player is using the exact same version of every mod. Use the "Sync with Server" feature to be sure.
• Version Mismatch: Some overhaul mods (like Space Exploration) require specific experimental builds of Factorio.

Expand the factory. View plans.