How to Mod Stardew Valley: SMAPI, the Mods Folder, Co-op and Servers

Modding Stardew Valley takes two steps: install SMAPI, the mod loader, and unzip each mod into the game's Mods folder. That's all it takes for single player. Co-op needs a bit more care, because some mods change the world everyone shares and every player has to have them, while others only change what you see on your own screen.

This guide covers how to mod Stardew Valley on Windows, macOS and Linux, the three kinds of mods you'll come across, which ones your friends need too, and how to add mods to a GameServerKings Stardew Valley server. The server part matters because the server doesn't run a normal SMAPI setup. It's missing some things and adds others, and knowing which saves you a lot of guessing.

Versions this page was checked against

Stardew Valley 1.6.15 (the current patch, released 20 December 2024) · SMAPI 4.5.2 (current release, for your PC) · SMAPI 4.3.2 (the version the GSK server installs). Both SMAPI versions need game version 1.6.14 or later.

Step 1: Install SMAPI on your PC

SMAPI (Stardew Modding API) loads the mods, rewrites them to work on your operating system, catches their errors and turns off mods it knows are broken. Almost every current mod needs it. Get it from smapi.io, not a re-upload.

Before you install it, launch the game once without mods so it can finish its first-time setup.

With the Steam launch option set, you keep playing through Steam as usual, and achievements and the overlay still work. A second window, the SMAPI console, opens next to the game. That window is where you'll see what loaded and what didn't.

To update SMAPI later, run the new installer over the old one. It cleans up the previous version by itself.

Step 2: Find your Mods folder

SMAPI creates a Mods folder inside the game folder. The default game folders are:

Can't find it? Type show_game_files in the SMAPI console and it opens the folder for you.

Step 3: Know what kind of mod you downloaded

Most Stardew mods come from Nexus Mods. The official wiki recommends avoiding ModDrop. Open the zip before you install anything and check what's inside:

Content packs catch out most new modders. The pack does nothing without its framework, and SMAPI will tell you so (see the troubleshooting table below).

Step 4: Install, configure and update mods

1. Unzip the mod somewhere outside Mods first.
2. Move the mod's folder into Mods. Every mod needs its own folder with its manifest.json directly inside it:

Stardew Valley/
└── Mods/
    ├── ContentPatcher/
    │   ├── ContentPatcher.dll
    │   └── manifest.json
    └── [CP] Some Content Pack/
        ├── content.json
        └── manifest.json

3. Launch the game through SMAPI. The console lists every mod that loaded, then a separate count of content packs.

Some more things worth knowing:

• Settings. Many mods create a config.json the first time they run. Close the game before you edit it, or your changes may not stick.
• Organising. You can group mods into subfolders (Mods/Farming/...), since SMAPI looks inside each one. To turn a mod off without deleting it, put a dot at the start of its folder name, like .PineappleMod.
• Updating. Deleting the old folder and installing the new one is the cleanest way. If you want to keep your settings, copy the new files over the old folder and keep its config.json.
• Compatibility. Before you install an older mod, check the mod compatibility list at smapi.io/mods. SMAPI turns off mods it knows are broken, even if you don't check.
• Save backups. SMAPI keeps a backup of your saves every day in Mods/SaveBackup.

Mods are only possible on PC and Android. Switch, PlayStation, Xbox consoles and iOS can't load them.

Mods in co-op: who needs what

Every player runs their own SMAPI with their own mods. What matters is whether a mod changes the shared world or just your screen. The Stardew Valley wiki's multiplayer rules:

Big content mods like Stardew Valley Expanded sit in the strictest rows. Every player, and the server, needs them at matching versions (see How to Install Stardew Valley Expanded). Mods like Lookup Anything or CJB Cheats Menu only change your own game, so each player can decide for themselves.

The simplest way to avoid problems is for the group to agree on one list of "world" mods at fixed versions, and for everyone to install them from the same zips.

Adding mods to a GameServerKings Stardew server

Stardew Valley doesn't have a separate dedicated-server program. A GSK Stardew server runs the full game with SMAPI on a virtual screen, and a host player plays the farm around the clock (see Stardew Valley Multiplayer for how it's set up). That means server-side modding is ordinary SMAPI modding, with a few things you won't have on your own PC.

What's already in the server's Mods folder

Our installer puts SMAPI and five mods in the Mods folder in the server root. These mods are what let the server host by itself, so don't remove them:

Two settings are rewritten by the panel on every start. The player limit in UnlimitedPlayers/config.json comes from the Player Limit variable, and the port in StardewPortChanger/config.json comes from your main allocation. Change those in the panel. Edits to those two values in the files won't survive a restart.

Reinstalling the server resets the configs of Auto Hide Host, Auto Load Game and Port Changer, and installs SMAPI 4.3.2 again. Back up any config you've customised first.

Check the SMAPI version before you upload

The server runs SMAPI 4.3.2, the version our installer pins. Your PC will probably have 4.5.2. Most mods work on both, but look at the mod's manifest.json first:

"MinimumApiVersion": "4.1.10"

If that number is 4.3.2 or lower, it runs on the server. For example, Content Patcher, Automate and Chests Anywhere need 4.1.10, and Lookup Anything needs 4.3.1. If it's higher, the server skips the mod and the console says: "it needs SMAPI 4.x.x or later. Please update SMAPI to the latest version to use this mod." Contact support in that case, and keep the older version of the mod on the server and on every player's PC until then.

Upload the mods

1. Stop the server and take a backup.
2. Connect over SFTP and open Mods/ in the server root.
3. Upload each mod's folder, with its manifest.json directly inside it, next to the folders already there. Upload the same versions your players have.
4. Start the server and watch the console. SMAPI lists what loaded, and anything it rejected under Skipped mods.
5. If a mod created a config.json on first start, stop the server, edit the file over SFTP, and start again.

Some things to know about the server:

• Mods that change time or dates can clash with Always On Server. Its author warns that "anything that messes with the game time/date is likely to cause issues."
• Mods that need a new save, like SVE, need you to create that farm on the server once over VNC. Set your own VNC Password in the Startup tab before you turn VNC on, because the installer's default is publicly known.
• Local-only mods (UI, minimaps, cheat menus for your own character) don't need to go on the server at all.
• The panel's console is the SMAPI console, so SMAPI commands like help or list_items work there. See Stardew Valley Cheats and Console Commands.

Troubleshooting: reading the SMAPI console

SMAPI explains why it rejected a mod in its own words. These are the messages you'll see most often, with what they mean:

If the list of skipped mods is long, fix the first dependency it names. Mods that depend on it will often load once it does.

If players can't reach the server at all, that's a network problem, not a mod one. See Players Can't Connect to My Server.

What to Read Next

• How to Install Stardew Valley Expanded (Solo, Co-op and on a Server): the biggest content mod, step by step, including the new-farm requirement
• Stardew Valley Multiplayer: How to Play With Friends (and Keep the Farm Online 24/7): how the server's host, VNC screen and player limit work
• Stardew Valley Cheats and Console Commands (SMAPI, Debug and Chat): what the SMAPI console can do once it's installed
• How to upload files via SFTP: for uploading mod folders to the server
• How to create a backup: take one before adding or updating mods

Made with 💜 by GameServerKings