Modding:Installing SMAPI on Windows

This page explains how to install SMAPI (the tool which lets you use mods) on Windows. See also:

• Instructions for Android
• Instructions for Linux
• Instructions for Mac

Install SMAPI

1. Run the game without SMAPI at least once (so it can do first-time setup).
2. Install .NET 5 (desktop x64):
   

   File:Modding - .NET 5 download on Windows.png

   The specific version required.

3. Download the latest version of SMAPI.
4. Extract the .zip file somewhere (but not in your game folder, any subfolder of your game folder, or in a folder with parentheses in the path!) (Your downloads folder is a fine choice).
5. Double-click install on Windows.bat¹, and follow the on-screen instructions.
6. See Configure your game client for the final steps.

¹ To install manually instead, see instructions in the installer's readme.

Configure your game client

Steam

You need to launch SMAPI through Steam if you want the Steam overlay, achievements, and playtime tracking to work. (If you don't care about achievements or tracking game time, you can just launch StardewModdingAPI.exe in your game folder to play with mods.)

Here's how to configure it:

1. Keep SMAPI's installer window open.
   (If you already closed it, just run it again. No need to uninstall first.)
2. Copy the text in the installer window that looks like this (see how to copy text):
   
   Make sure you copy the entire line, including both quotation marks " and the %command% part.
   Your final path should look something like this: "Your path here" %command%
3. In the Steam client, right-click on Stardew Valley and choose Properties:
   
4. Click the textbox under Launch Options:
   
5. Replace anything in the textbox with the text you copied from the installer.
   To paste text, click in the box and press CTRL and V.
6. This text should consist of "Your SMAPI API Filepath" %command%
   Default for most users is "C:\Program Files (x86)\Steam\steamapps\common\Stardew Valley\StardewModdingAPI.exe" %command%
7. From now on, just launch the game through Steam to run SMAPI with the Steam overlay and achievements.

GOG Galaxy

You need to launch SMAPI through GOG Galaxy if you want its playtime tracking to work. (If you don't care about tracking game time, you can just launch StardewModdingAPI.exe in your game folder to play with mods.)

Here's how to configure it:

1. Open Notepad and paste in the following: start "" "C:\Program Files (x86)\GOG Galaxy\Games\Stardew Valley\StardewModdingAPI.exe" If Stardew Valley and SMAPI are not installed at C:\Program Files (x86)\GOG Galaxy\Games\Stardew Valley\, (the default location for most people), replace that location with the location of where you installed Stardew Valley.
2. Click on File, then Save As...
   
3. Navigate to your Stardew Valley installation folder and change the file type from Text Documents to All Files as shown below and then click Save.
   
4. Then type start.bat for the file name as shown below
   
5. In the GOG Galaxy client, click on Stardew Valle' and then the settings icon on the right-hand side of the 'Play' button, then hover over 'Manage installation' and click 'Configure...' as shown below.
   
6. A new menu will appear. Check the "Custom executables / arguments" box.
   
7. Then click 'Add another executable / arguments'
   
8. Select start.bat in the window that appears and then click Open.
   
9. Finally, click the circle next to 'Default Executable' underneath File 2, then click OK.
   
10. From now on, you can launch Stardew Valley through GOG Galaxy and both the SMAPI console and game will load as expected!

Xbox app

Mods work with the Xbox app, but there's a few extra steps.

Before you install SMAPI:

1. Open the Stardew Valley section in the Xbox app.
2. Click the "Enable Mods" button:
   
3. Click the "Open Mods Folder" button to open your game folder in the file explorer:
   
4. Copy the full path from the address bar at the top.

Run the SMAPI installer:

1. Run the SMAPI installer like usual, but when it asks where to install, enter the path you copied from the previous step.

After you install SMAPI:

1. In your game folder:
   1. rename Stardew Valley.exe to another name such as Stardew Valley original.exe;
   2. rename StardewModdingAPI.exe to Stardew Valley.exe.
2. Launch the game through the Xbox app. (You won't be able to launch the new Stardew Valley.exe directly yourself.)

Update SMAPI

Just install the new version; the installer will automatically clean up previous versions. (You don't need to configure Steam or GOG Galaxy again.)

Uninstall

1. Run run the installer again, but choose uninstall to remove SMAPI. (Not applicable for Xbox app.)
2. If you configured Steam or GOG Galaxy to launch SMAPI, undo your changes:
   • Steam: in the Steam client: right-click on Stardew Valley, choose Properties > General > Set Launch Options, and blank the launch options textbox.
   • GOG Galaxy: in the GOG Galaxy client: click on Stardew Valley, click the settings icon next to the 'Play' button, click Manage installation > Configure, and clear the Custom executables / arguments checkbox.
   • Xbox app:
   1. follow the installation steps for Xbox app to open your game folder;
   2. rename Stardew Valley.exe to StardewModdingAPI.exe;
   3. rename the orginal exe that you renamed when you installed SMAPI back to Stardew Valley.exe.

(If you want to play without mods temporarily, you can just launch Stardew Valley.exe directly or rename your Mods folder instead. Not applicable for Xbox app.)

Troubleshooting

"Oops, couldn't find the game automatically"

If you are using Game Pass, folder permissions will probably cause problems if you try this. Otherwise, if the installer shows that message, you can help it find the game folder. To do that:

1. Exit the installer.
2. Find your game folder.
3. Move the installer folder into the game folder. (Make sure you move the whole folder, not just the files inside it!)
4. Run the installer again and it should auto-detect the game folder now.

You can safely delete the installer folder when it's done.

Issues with SMAPI or mods

See the troubleshooting page for help with issues after installation.

← Getting Started