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...

1. 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.
2. 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. Click the right link for more info:

• Instructions for Linux
• Instructions for Mac
• Instructions for Windows

Find mods

Next you can download the mods you want. Some suggestions:

• most popular mods on Nexus;
• recommendations for a first playthrough;
• search for mods here:

  site	description
  Nexus Mods	Most mods are released here. (Registering an account is free, just don't choose a package when you register.)
  Chucklefish mods	Some mods are released here (most are also on Nexus).
  ModDrop	Pretty new. Not many mods yet, but you can install those it has very quickly through their (Windows-only) client.
  Stardew Valley forums	Some mods are posted directly in the forums. Some hidden gems are only here, but finding them can be a challenge.

Before you download a mod...

• Does it work with the latest version of the game? (SMAPI will automatically disable most incompatible SMAPI mods, but you're on your own with XNB mods. Try checking the mod description or comments.)
• Don't download from stardewvalleymods.net. (Mods here are usually outdated, since the site republishes mods without permission for ad revenue.)

Find your game folder

Next you'll need to open your game folder (the one containing Stardew Valley's .exe file). 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
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

Not there? Here are some other ways to find it:

more options

Option 2: find it through SMAPI Launch SMAPI. Enter this command in the SMAPI console (the second window that opens with the game): show_game_files Option 3: find it through Steam Open the Steam client. Right-click on Stardew Valley. Click Properties. Click the Local Files tab. Click the Browse Local Files... button to open the game folder. Option 4: find it through GOG Galaxy Open the GOG Galaxy client. In the game sidebar, right-click on Stardew Valley. Choose Manage Installation > Show Folder to open the game folder.

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

If you have a lot of mods, you can optionally organise 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

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.

If you want to disable a folder, just add a dot in front of the folder name (like .disabled mods). Windows won't let you do that by default, but just put a dot at the end too and it'll let you (like .disabled mods.).

Configure mods

Some mods have a config.json file in their mod folder. It might be created the first time you launch the game with that mod. This file lets you customise the mod settings.

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

To update a mod, just replace its files with the new versions (making sure to keep generated files like config.json).

More detailed steps:

1. Download the new mod version.
2. Unzip it somewhere else (not in your Mods folder).
3. Open the mod's old and new folders, so the manifest.json is visible in both.
4. 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

Can I use mods on Linux, Mac, Windows, or consoles?

Mod support for each platform:

Platform	Mod support
Linux	✓ fully supported
Mac	✓ fully supported
Windows	✓ fully supported
Nintendo Switch	✖ no mod support
PS4	✖ no mod support
XBox One	✖ no mod support
Android	See Android modding.

Almost all mods will work on any supported platform, since SMAPI rewrites them for compatibility.

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	effects	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).
Visual changes	local	That includes custom portraits and sprites, custom farmer appearance (except GetDressed or Kisekae), recolors, etc. 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 though.
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, you can uninstall it anytime, and there's a friendly community if you need help. SMAPI is required for most types of Stardew Valley mod.

SMAPI does a lot for you. For example, it will...

1. Load mods into the game and provide APIs they can use. Many types of mod aren't possible without SMAPI.
2. Rewrite mods for crossplatform compatibility, so you can use almost any mod on Linux/Mac/Windows.
3. 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.
4. Provide update checks. SMAPI automatically alerts you when a new version of a mod is available.
5. 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 Troubleshooting#Find your SMAPI log.
• Save files: see Saves.

Can I have different mod groups?

You can create multiple Mods folders with different names (like Mods and Mods-MP) for use in different save files, testing, etc. After creating the folder, create a shortcut to your SMAPI file and open the Properties menu by right clicking on the shortcut. In Properties, find the Target line and add the following to the end --mods-path "*name of your mods folder*". Done correctly, it will look like this example "...\SteamLibrary\steamapps\common\Stardew Valley\StardewModdingAPI.exe" --mods-path "Mods-testing". You can now use that shortcut to open SMAPI with that mod folder.

Troubleshooting →