Modding:Player Guide/Getting Started
Do you want to play Stardew Valley with mods? This guide is for you!
Intro
A "mod" is just a package of files which changes Stardew Valley in some way. Mods can add features (like showing NPCs on the map), change game mechanics (like making fences decay more slowly), make cosmetic changes (like making your house look like a hobbit home), and more.
Using mods is easy! You just need to...
- Install SMAPI. That's the mod loader for Stardew Valley — it launches the game with mod support and lets mods interact directly with the game code. It's safely installed alongside your normal game, and you can uninstall it anytime.
- Unzip mods into your Mods folder.
See frequent questions below, or keep reading to get started!
Getting started
Install SMAPI
First you'll need to install the mod loader, SMAPI.
See the instructions for:
- Windows;
- macOS;
- Linux;
- Steam Deck (the handheld PC);
- or Android.
Find mods
Next you can download the mods you want. Some suggestions:
- most popular mods on Nexus;
- recommendations for a first playthrough;
- recommendations from other players;
- search for mods here:
site description Nexus Mods Most mods are released here.
An account is required, but it's free; just don't choose a package when you register.ModDrop Many mods are released here. Official forums Some mods are released here, though most are also on Nexus or ModDrop. Chucklefish mods Some older mods are released here, though most are also on Nexus or ModDrop. Chucklefish forums Some older mods are posted directly in the Chucklefish forums. Some hidden gems are only here, but finding them can be a challenge.
Before you download a mod, check if it works with the latest version of the game. For SMAPI mods, see the mod compatibility list; SMAPI will also automatically disable most incompatible SMAPI mods. You're on your own for XNB mods; try checking the mod description or comments for those.
Find your game folder
Next you'll need to open your game folder (the one containing Stardew Valley.exe
or StardewValley.exe
). Here's where to find it by default:
Platform | Path |
---|---|
Windows | GOG: C:\Program Files (x86)\GOG Galaxy\Games\Stardew Valley or C:\GOG Games\Stardew Valley Steam: C:\Program Files (x86)\Steam\steamapps\common\Stardew Valley Xbox App: C:\XboxGames\Stardew Valley
|
Android | /storage/emulated/0/StardewValley/Mods (Usually file manager apps show StardewValley in the root)
|
Linux | GOG: ~/GOGGames/StardewValley/game Steam: ~/.local/share/Steam/steamapps/common/Stardew Valley
|
Mac | GOG: /Applications/Stardew Valley.app/Contents/MacOS Steam: ~/Library/Application Support/Steam/SteamApps/common/Stardew Valley/Contents/MacOS
See also a pictorial guide to finding the folder on macOS. |
Not there? Here are some other ways to find it:
more options |
---|
For images, please see Modding:Installing_SMAPI_on_Windows#Xbox_app |
Install mods
To install a mod, just unzip it into the Mods
folder in your game folder. Make sure each mod has its own subfolder, without trailing numbers. For example, if you have a PineapplesEverywhere
mod, you should have a file structure like this:
📁 Stardew Valley/ 📁 Mods/ 📁 PineapplesEverywhere/ 🗎 PineapplesEverywhere.dll 🗎 manifest.json
Tips:
- If you have a lot of mods, you can optionally organize them into subfolders. SMAPI will automatically search inside each folder until it finds one with files.
📁 Stardew Valley/ 📁 Mods/ 📁 Fruit mods/ 📁 PineapplesEverywhere/ 🗎 PineapplesEverywhere.dll 🗎 manifest.json 📁 ApplesNowhere/ 🗎 ApplesNowhere.dll 🗎 manifest.json
- To disable a folder, just add a dot in front of the folder name (like
.disabled mods
). If Windows doesn't let you do that, put a dot at the end too and it'll let you (like.disabled mods.
). - Download mods into a folder other than
Mods
, unzip them there, and then move their folder(s) intoMods
. That helps prevent errors related to extra files. - If you have a folder that looks like
PineapplesEverywhere-1234567890
, check inside it for the actual mod folder. Folders named like this often have more folders and possibly readme files inside them.
Configure mods
Some mods have a config.json
file in their mod folder, which lets you customise the mod settings. The file is usually created the first time you launch the game with that mod installed.
To edit the config.json
file, just open it in a text editor. Make sure the game isn't running when you edit it, or your changes might not take effect. See a basic guide to JSON; basically make sure your values are surrounded by quotes (like "value"
). You can use this JSON validator to make sure the format is correct.
Update mods
There are two main ways to update a mod. Before updating a mod, don't forget to check its mod page for any special update instructions.
- Clean update
- Just delete the mod from your Mods folder, then install the new version normally. This is the safest way to update (since it removes any old files), but it'll also reset any mod settings to their default values.
- Merge update
- If you want to keep your old settings, you can replace the mod's files with the new versions while keeping generated files like
config.json
.
- To do that:
- Download the new mod version.
- Unzip it somewhere else (not in your
Mods
folder). - Open the mod's old and new folders, so the
manifest.json
is visible in both. - Copy all the files/subfolders from the new folder into the old folder.
Remove mods
Delete a mod from the Mods
folder to uninstall it. Make sure to check the mod page in case it mentions any special uninstall instructions.
XNB mods
XNB mods replace files in your game's Content
folder with custom versions. If a mod has some .xnb
files and no manifest.json
, it's an XNB mod. This is an older type of mod that's no longer recommended, but see Modding:Using XNB mods if you're still interested.
Frequent questions
Which platforms allow mods?
Mod support for each platform:
Platform | Mod support | |
---|---|---|
PC | Linux / SteamDeck* | ✓ fully supported |
Mac | ✓ fully supported | |
Windows | ✓ fully supported | |
console | Nintendo Switch | ✖ no mod support |
PS4 | ✖ no mod support | |
PS Vita | ✖ no mod support | |
XBox One | ✖ no mod support | |
mobile | Android | ✓ most mods supported |
iOS | ✖ no mod support |
*Modding on SteamDeck may increase power usage.
Almost all mods will work on any supported platform, since SMAPI rewrites them for compatibility.
(For more technical info, see the SMAPI tracking ticket.)
Can mods corrupt my save?
Yes, but it's extremely rare. Only a few mods affect your save file at all. If you avoid those, mods are very unlikely to corrupt your save file. In most cases, you can fix save corruption by undoing the last save.
If you're worried, just back up your save files occasionally. That's strongly recommended even if you don't use mods, since save corruption is almost always caused by the game itself. SMAPI also creates a daily backup of your saves automatically; you can retrieve those from the Mods/SaveBackup folder.
Can I stop using mods later?
Yep. With a few exceptions (see previous question), mods don't directly affect your save file so you can stop using them anytime.
Do mods disable Steam achievements?
Steam achievements work fine, as long as you launch SMAPI through Steam. Make sure you follow the install instructions to configure Steam on Windows (no Steam changes needed on Linux or Mac). If the Steam overlay works, the achievements should work too.
Do mods work in multiplayer?
Yep, but it depends on the mod. Usually each player can have their own mods, and you can mix modded and vanilla players. Some mods don't work (or work poorly) in multiplayer, or affect other players too. Try checking the mod description for details about multiplayer (often under a 'compatibility' header).
Here are some approximate rules for mods that don't specify:
type of mod | affects | summary |
---|---|---|
Content Patcher | depends | See Multiplayer in the Content Patcher readme (applies for XNB mods too). |
Map replacements | local | That includes mods which replace an existing map (without adding special logic with SMAPI). These are only visible to players who install them. Players without the custom map will see the normal map and will be subject to the normal bounds (e.g., they may see other players walk through walls, but they won't be able to follow). |
Custom items | global | That includes new crops, fruit trees, craftables, cooking recipes, furniture, wallpapers and floors, weapons, rings, clothing, and hats. Mods which add new items should be installed by all players; players missing a custom item mod may see Error Items. |
Custom locations | global | That includes new locations and buildables added by TMXL or other frameworks. All players should have the same location mods. Entering a custom location that not everyone has installed can cause crashes. Buildables can only be built by the main player. |
Custom NPCs | global | That includes any mod that adds new characters to the game. All players should have the same custom NPCs installed to avoid issues. |
Visual changes | depends | That includes custom portraits and sprites, custom farmer appearance, recolors, etc. Most of these mods only affect the players who installed them. Other players won't be affected. If both players have the same mods, they'll see the same visual changes. The exception is Content Patcher farmer appearance mods that add, rather than recolor, the existing sprites. All players need to have the same amount of new sprites (e.g., hairstyles or shirts) or there can be visual bugs for other players. |
"Cheat"/"efficiency" mods | local | That includes mods that increase player speed, make farm tasks easier, give infinite energy, spawn items, etc. Other players will see the effects, but won't be able to use the mod unless they have it installed. It won't affect other players. |
Time changes | global | That includes any mod which pauses time, changes the current time, or changes the rate of time. These mods only work when installed by the main player, but will affect all players. They will have no effect when used by farmhands. |
Custom UI | local | That includes mods that add new icons, tooltips, and menus. These mods only affect the players who installed them. Other players won't be affected. |
World changes | global | That includes any mods which edit things in the world — durable fences, monster stat changes, etc. These mods affect all players, no matter who installs them. |
Other mods | depends | See the mod's description for details, or ask the author. |
What is SMAPI?
SMAPI is the mod loader for Stardew Valley. It works fine with GOG and Steam achievements, it's compatible with Linux/Mac/Windows and (unofficially) Android, you can uninstall it anytime, and there's a friendly community if you need help. SMAPI is required for most types of Stardew Valley mods.
SMAPI does a lot for you. For example, it will...
- Load mods into the game and provide APIs they can use. Many types of mods aren't possible without SMAPI.
- Rewrite mods for crossplatform compatibility, so you can use almost any mod on any platform.
- Intercept errors. If a mod crashes or causes an error, SMAPI will intercept the error, show the error details in the console window, and in most cases automatically recover the game.
- Provide update checks. SMAPI automatically alerts you when a new version of a mod is available.
- Provide compatibility checks. SMAPI automatically detects when a mod is incompatible and disables it before it causes problems.
Where are my...
- Game folder: see Getting Started#Find your game folder.
- SMAPI log: see smapi.io/log (and Modding:Help if you need help with something).
- Save files: see Saves.
Can I have different mod groups?
Yep, SMAPI has built-in support for different mod groups. The instructions may seem complex, but it's easy once you get the hang of it:
For simplicity, you can also just rename the Mods folder to something else.
Platform | Instructions |
---|---|
Windows |
|
Windows (Steam) |
|
Windows (Steam, Non-Steam Game Method) |
|
Linux |
|
Mac |
|
On Windows only, the ModDrop mod manager also supports up to three 'mod loadouts' which you can switch between.