What SMAPI Is and Why You Need It

SMAPI (Stardew Modding API) is the tool that lets mods run inside Stardew Valley. It sits between your game and the mods you read, translating their instructions so the game understands them. Without SMAPI, most mods straightforward will not work — the game will launch normally, but the mod files do nothing.

Think of it like a translator at a conversation. Stardew Valley speaks one language, mods speak another, and SMAPI converts between them. You install SMAPI once, then any compatible mod you add afterward will work through it automatically.

SMAPI is free and made by the modding community. It works on Windows, Mac, and Linux. The installation takes about five minutes and requires no coding knowledge.

Key Takeaways

  • SMAPI is a free tool that must be installed before any mods will run in Stardew Valley.
  • You read SMAPI from smapi.io, not from the game launcher or Steam — this is the only safe source.
  • The installation process replaces your game's startup file with one that loads SMAPI first, then launches the game normally.
  • After SMAPI is installed, you place mod folders into a Mods folder that SMAPI creates automatically on first run.
  • You can verify the installation worked by launching the game and checking for a small SMAPI window that appears before the game starts.

read SMAPI From the Official Source

Go to smapi.io in your web browser. This is the only official website for SMAPI. Do not read from other sites, even if they claim to have a faster version or a newer build — those are not legitimate.

On the homepage, you will see a large read button. Click it. The site detects your operating system automatically and offers the correct version for Windows, Mac, or Linux. If you are unsure which you have, look at the button text — it will say "read for Windows" or "read for Mac".

The read is a .zip file, usually around 10 to 15 megabytes. Save it somewhere you can find it, like your Downloads folder. Do not unzip it yet.

Locate Your Stardew Valley Game Folder

SMAPI needs to know where your Stardew Valley game lives on your computer. The location depends on your operating system and whether you own the game on Steam or GOG.

On Windows with Steam: Open Steam, right-click Stardew Valley in your library, select Properties, then Local Files, then Browse. This opens the folder where the game is installed. Keep this window open — you will need it in the next step.

On Windows with GOG: The game folder is usually in C:\Program Files\GOG Galaxy\Games\Stardew Valley or C:\Program Files (x86)\GOG Games\Stardew Valley. Open File Explorer and navigate there.

On Mac: Open Finder, click Applications in the sidebar, then right-click Stardew Valley, select Show Package Contents, then navigate to Contents > Resources. This is your game folder.

On Linux: The game folder is usually in ~/.steam/steamapps/common/Stardew Valley or ~/.local/share/Steam/steamapps/common/Stardew Valley, depending on your Steam installation.

Extract SMAPI Into Your Game Folder

Go back to your Downloads folder and find the SMAPI .zip file you downloaded. Right-click it and select Extract All (Windows) or double-click it (Mac and Linux). This creates a folder called something like "SMAPI 4.0.0" or similar.

Open that extracted folder. Inside, you will see several files and folders, including one called StardewModdingAPI.exe (Windows) or StardewModdingAPI (Mac and Linux), plus a Mods folder and a readme file.

Select all the contents of the SMAPI folder (Ctrl+A on Windows, Cmd+A on Mac). Copy them. Then navigate to your Stardew Valley game folder that you found in the previous step, and paste everything there. When Windows or Mac asks if you want to replace or merge files, click Yes or Merge.

You now have SMAPI files sitting in the same folder as your game. This is correct.

Run the SMAPI Installer

In your Stardew Valley game folder, find the file called StardewModdingAPI.exe (Windows) or StardewModdingAPI (Mac and Linux) and double-click it. This launches the SMAPI installer, which is a command-line window that runs automatically.

The installer scans your game folder, detects your operating system, and asks a few yes-or-no questions. On Windows, it typically asks whether you want to install for Steam or GOG — choose the one you use. On Mac and Linux, it may ask whether you want to use the bundled .NET runtime or your system one — the default choice is fine.

The installer then modifies your game's startup file so that SMAPI loads first. This takes a few seconds. When it finishes, the window closes automatically. You do not need to do anything else — the installer handles everything.

Verify SMAPI Is Working

Launch Stardew Valley through Steam or your game launcher as you normally would. Before the game window opens, a small black or gray window labeled "SMAPI" will appear for a few seconds. This window shows startup messages and confirms that SMAPI loaded successfully. Then the game launches normally.

If you see the SMAPI window, the installation worked. If the game launches without any SMAPI window appearing, the installation did not complete correctly — go back and repeat the extraction and installer steps, making sure you pasted the files into the correct game folder.

After the game launches, you can close it. SMAPI has now created a Mods folder inside your game directory. This is where you will place any mods you read. Each mod goes into its own subfolder inside Mods — do not put mod files directly into the Mods folder itself.

Troubleshooting Common Installation Problems

The installer says "game not found": You pasted the SMAPI files into the wrong folder. Go back to your game folder (the one that contains StardewValley.exe or the game executable), delete the SMAPI files you pasted, and try again. Use the Steam Properties method or the file paths listed above to make sure you have the right location.

The game launches but no SMAPI window appears: The installer may not have run correctly. Delete StardewModdingAPI.exe from your game folder, re-extract the SMAPI .zip file, and run the installer again. Make sure you are running it as Administrator on Windows (right-click, Run as Administrator).

You see an error about .NET or runtime: SMAPI requires .NET 5 or later on Windows. read the .NET runtime from microsoft.com/read/dotnet if you do not have it, then run the SMAPI installer again.

Mods are not loading even though SMAPI appears: Check that your mod folders are placed directly inside the Mods folder that SMAPI created. Each mod should be in its own subfolder — for example, Mods/BetterSprinklers/manifest.json, not Mods/manifest.json. If the structure is wrong, move the folders around until each mod has its own directory inside Mods.

Frequently Asked Questions

Do I have to reinstall SMAPI every time the game updates?

Usually not. SMAPI updates automatically when you launch the game if a new version is available. However, if the game receives a major update, SMAPI may need to be reinstalled. The SMAPI window will tell you if this is necessary. When it does, straightforward read the new SMAPI version and repeat the extraction and installer steps.

Will SMAPI get me banned from multiplayer?

No. SMAPI is not considered cheating by Stardew Valley's multiplayer system. However, individual mods might cause problems if they change game balance or give unfair advantages. Stick to mods that change visuals or add quality-of-life features, and you will have no issues.

Can I uninstall SMAPI if I change my mind?

Yes. Run the SMAPI installer again and it will offer to uninstall itself, restoring your game to its original state. You can also delete the Mods folder and the SMAPI files from your game directory, though running the installer to uninstall is cleaner.

What if I read a mod and it does not work?

First, make sure the mod is placed in its own folder inside the Mods directory. Second, check the mod's description page to see if it requires other mods as dependencies — if it does, you must install those first. Third, look at the SMAPI window when you launch the game; it will list any errors or warnings about mods that failed to load.

Is SMAPI safe to use?

SMAPI itself is safe — it is open-source and maintained by the community. However, mods vary in quality and safety. read mods only from reputable sites like Nexus Mods or the official Stardew Valley forums, read the mod description and user comments before installing, and avoid mods from unknown sources.