Factorio mods in depth

Factorio's mod system is clean once you see how the pieces fit: a folder of mod files, a list that says which are on, and a set of rules about dependencies and versions that Factorio checks before it starts. A headless server adds one honest wrinkle — it can't browse or download mods the way the game client can, so you feed it the files yourself. This guide covers the whole loop.

The mods folder and mod-list.json

Everything lives in the server's mods folder, reachable in the File Manager. Two kinds of thing sit there:

mod-list.json looks like this:

{
  "mods": [
    { "name": "base", "enabled": true },
    { "name": "boblibrary", "enabled": true },
    { "name": "bobores", "enabled": false }
  ]
}

Add a mod's zip to the folder and Factorio adds it to this list (enabled) on the next start. To turn a mod off without deleting it, flip its enabled to false here — the zip stays, the mod sleeps. base is Factorio itself; leave it enabled.

Dependencies: mods that need other mods

Many mods build on a shared library or another mod. Each mod declares what it needs in its own info.json (dependencies), and Factorio refuses to start if a required dependency is missing — it prints exactly which one at the top of the console. So a mod is rarely "one file":

• Required dependencies must all be present, or the server won't boot.
• Optional dependencies only change behavior when both mods are installed.
• Load order is handled for you — Factorio sorts mods by their dependencies automatically.

💡 Tip: When the console stops with a "missing dependency" line, read the mod name it gives you, add that mod's zip to the folder, and start again. Big overhaul mods can pull in a chain of these — add them until the console is happy.

Version matching (two kinds)

Factorio is strict about versions, in two directions:

• Mod ↔ Factorio. Every mod's info.json names the factorio_version it targets (like 1.1 or 2.0). A mod built for a different major version won't load. Match your mods to your server's Factorio version.
• Mod ↔ dependency. A mod can require a minimum version of another mod. If your library mod is too old, the mod that needs it won't load until you update it.

⚠️ Heads up: And the rule from multiplayer that never changes: every player needs the same mods at the same versions as the server. The server won't let a mismatched client join. Line the lists up before you invite anyone.

Getting the mod files onto a headless server (the honest part)

This is where a hosted server differs from playing on your PC:

⚠️ Heads up: A headless Factorio server has no in-game mod browser and does not download mods for you. You put the mod .zip files in the mods folder yourself, then restart.

So the reliable workflow is manual and simple:

1. Get each mod's .zip from Factorio's official mod portal, mods.factorio.com. Downloading from the portal needs a logged-in factorio.com account, and that account requires a valid Factorio license — there's no way around the login, and that's by design.
2. Grab the mod and its dependencies, all for your server's Factorio version.
3. Upload the zips into the server's mods folder with the File Manager (or SFTP for a big set).
4. Restart and read the console — Factorio loads each mod or tells you what's missing.
5. Hand the same mods and versions to every player.

That's the whole thing. Some setups automate portal downloads with account credentials, but the credential handling there varies and moves around, so the stable, always-works path is: download from the portal, upload the zips.

🎯 Good to know: Your save and mods live in the server's files and survive restarts, stops, and the free-plan sleep — but not a reinstall or a game switch. Take a backup before big mod changes; on free, backups save to your own Google Drive.

Verify it works

The Console is your proof: on start, Factorio lists the mods it loaded (and any it rejected), then hosts the game. When a friend on the matching mod set connects, their join shows in the log. If the console halts before hosting, read the top line — it's almost always a missing dependency or a version mismatch.

Troubleshooting

• Server won't start after adding a mod — a required dependency is missing, or the mod targets a different Factorio version. The console names the problem mod; add the dependency or match the version.
• A mod I added isn't active — it's set to "enabled": false in mod-list.json, or the zip's name/version doesn't match what the list expects. Flip it to true and restart.
• A player can't join — their mods or versions don't match the server's. Everyone needs the identical set; align them and retry.
• Save loads without the mods — the mods weren't enabled when it loaded. Confirm mod-list.json and restart before loading the save.

For per-mod details, dependencies, and every version, the source of truth is the official portal at mods.factorio.com.

Next steps

• Factorio server quickstart
• How free game servers work
• Automate and manage backups