HOLYMOD
Guide · Stardew Valley

How to install Stardew Valley mods with SMAPI

How to install Stardew Valley mods: SMAPI on Windows, Mac, Linux and Steam Deck, the Mods folder, Content Patcher, mod managers and log errors.

Updated: 24 Oct 2026

If you’re wondering how to install mods in Stardew Valley, the short answer is that you need SMAPI, the game’s mod loader: you install it once with its installer, and then you copy each mod into the Mods folder inside the game folder. The current version is SMAPI 4.5.2 (as of October 2026), which requires Stardew Valley 1.6.14 or later; the latest version of the game on PC is 1.6.15 (as of October 2026). It works on Windows, macOS, Linux and Steam Deck. On Android there’s only an unofficial port, and there are no mods on iOS or consoles.

Before you start

  • Launch the game once without mods and close it, so it can finish its initial setup.
  • Check your version. SMAPI 4.5.2 needs 1.6.14 or later. Many current mods, like Pathoschild’s, already require 1.6.15.
  • Create a Nexus Mods account. That’s where almost every mod and SMAPI itself are published, and you need a free account to download.
  • Only download from the official page. On every Holymod mod page we link to the author’s page. Some mods are also on CurseForge or GitHub; the wiki’s official player guide advises against ModDrop.

How to install SMAPI in Stardew Valley

The basic process is the same on every system: download SMAPI, unzip the .zip outside the game folder and run the installer for your system. After that, each system has its own details.

Windows: Steam, GOG and the Xbox app

  1. Double-click install on Windows.bat and choose to install.
  2. Steam: the installer shows you a line for the launch options. Copy it into the game’s Properties > Launch Options. It looks like this: "C:\Program Files (x86)\Steam\steamapps\common\Stardew Valley\StardewModdingAPI.exe" %command%.
  3. GOG Galaxy: create a start.bat file containing start "" "C:\Program Files (x86)\GOG Galaxy\Games\Stardew Valley\StardewModdingAPI.exe", add it as a custom executable (Configure > Custom executables / arguments) and set it as the default executable.
  4. Xbox app or PC Game Pass: during installation, enter the path to the Content folder (you’ll find it under Manage > Files). Then rename Stardew Valley.exe, for example to Stardew Valley original.exe, and put a copy of StardewModdingAPI.exe named Stardew Valley.exe in its place. You’ll have to repeat this after every game update.

Mac

  1. In System Settings > Privacy & Security, turn on Developer Tools for Terminal. If the option doesn’t show up, run spctl developer-mode enable-terminal in Terminal. Then restart.
  2. Right-click install on macOS.command and choose Open.
  3. If Gatekeeper blocks it, go to Privacy & Security and click Open Anyway.

On Mac you don’t need to touch Steam’s launch options.

Linux

  1. Open a terminal in the unzipped folder and set the permissions: chmod +x "./install on Linux.sh" "./internal/linux/SMAPI.Installer".
  2. Run ./install\ on\ Linux.sh from the terminal. Don’t open it by double-clicking: there’s a bug related to syslog.

On NixOS you use steam-run. If the installer fails to open the terminal, install xterm.

Steam Deck

  • Native Linux version: install it the same way as on Linux, with install on Linux.sh.
  • Windows version with Proton: use SMAPI for Windows with the manual installation described in its README (just copying the installer into the folder isn’t enough), add StardewModdingAPI as a non-Steam game and force Proton. Heads-up: with Proton, Steam Cloud doesn’t save your modded saves.

The wiki warns that on the Deck, mods can increase battery drain.

When you launch the game with SMAPI, a console window will open alongside it. There you’ll see which mods have loaded and which ones have failed.

The Mods folder: where it is and how to add mods

The installer creates the Mods folder inside the game folder. These are the usual game paths:

  • Steam (Windows): C:\Program Files (x86)\Steam\steamapps\common\Stardew Valley
  • GOG (Windows): C:\Program Files (x86)\GOG Galaxy\Games\Stardew Valley or C:\GOG Games\Stardew Valley
  • Xbox app: C:\XboxGames\Stardew Valley
  • Linux (Steam): ~/.local/share/Steam/steamapps/common/Stardew Valley
  • Linux (GOG): ~/GOGGames/StardewValley/game
  • macOS (Steam): ~/Library/Application Support/Steam/SteamApps/common/Stardew Valley/Contents/MacOS
  • macOS (GOG): /Applications/Stardew Valley.app/Contents/MacOS

If you can’t find it, type show_game_files in the SMAPI console and it will open the folder for you.

Installing a mod step by step

  1. On the mod’s page, open the Files tab and click Manual download on the main file.
  2. Unzip the .zip outside the game folder.
  3. Move the mod’s folder into Mods. Each mod goes in its own subfolder, with its manifest.json file. You can group them into subfolders (for example, one for expansions), because SMAPI looks inside them.
  4. Install its dependencies the same way.
  5. Launch the game with SMAPI and check in the console that the mod shows up with no red errors.

To disable a mod without deleting it, put a dot in front of its folder name.

Content Patcher and dependencies

Many mods don’t work on their own: they need other mods, called frameworks, that act as a base. The most important one is Content Patcher: on its own it doesn’t change anything, but it loads content packs, mods that change the game’s data, images and maps. Portraits, retextures, new NPCs and expansions depend on it.

  • Folders starting with [CP] are Content Patcher packs, and those starting with [FTM] are for Farm Type Manager. You install them the same way, in Mods, and they need their framework.
  • SpaceCore is another widely required library: according to its page, more than 780 mods use it.
  • Generic Mod Config Menu is optional, but it lets you change mod options from inside the game, without opening config.json files.

An example: Stardew Valley Expanded requires SMAPI, Content Patcher and Farm Type Manager, and Ridgeside Village also requires Custom Companions and SpaceCore. Every Holymod mod page lists the required and optional dependencies. If you launch the game and one is missing, the SMAPI console will tell you which.

Mods in Spanish

Mods that support translation have an i18n folder with one file per language; the Spanish one is es.json. The mod automatically uses the game’s language and, if a line is missing, shows it in English. On top of that, Nexus has lots of Spanish translations published as separate mods: you install them by copying their es.json into the mod’s i18n folder, or however each translation says. Before installing them, check that their version matches the mod’s. An outdated translation leaves text in English or untranslated keys.

Updating and uninstalling

Updating SMAPI

Download the new version and run its installer: it removes the old one. When a game update comes out, some mods may stop working until their authors update them, so don’t rush to update if your save depends on lots of mods.

Updating mods

SMAPI tells you in the console when there are new versions of the mods you have installed. To update one, you have two options:

  • Clean: you delete the mod’s folder and copy in the new one. You lose your config.json.
  • Merged: you overwrite the files and keep your config.json. Read the mod’s instructions first, in case it asks for something else.

Uninstalling

  • A single mod: delete its folder from Mods.
  • SMAPI: run the installer and choose uninstall. On Steam for Windows, also clear the launch options field.

Common errors and the SMAPI log

  • A mod won’t load. Check the SMAPI console: it tells you which mod failed and, if a dependency is missing, which one.
  • A [CP] pack does nothing. Check that Content Patcher shows up among the loaded mods.
  • The mod is for a different version. Several mods keep files for 1.5.6 with different requirements. On 1.6, always download the main file for 1.6 and don’t mix versions.
  • Mods break after a game update. Wait for their authors to update them. On the Xbox app, also redo the executable rename.
  • On Linux the installer does nothing. Run it from a terminal, not by double-clicking.
  • English text or weird keys. It’s usually a separate translation that doesn’t match the mod’s version.

If the problem isn’t clear, upload your SMAPI log to smapi.io/log, SMAPI’s log parser. It displays the log neatly with the errors highlighted, and it’s what you’ll be asked for on any mod’s forums if you ask for help.

Mod managers: Stardrop, Vortex or by hand

We recommend starting with manual download (Manual download on Nexus and unzipping into Mods), which works with every mod. If you have a lot of them, a manager saves you work:

  • Stardrop (by PeacefulEnd, open source, for Windows, macOS and Linux): version 1.10.4 (as of October 2026). It uses SMAPI to manage mods and check for updates, and it has mod profiles, which are handy for multiplayer. With Nexus’s Mod manager download button it installs in one click on Windows and macOS. It’s the manager mentioned in the wiki’s player guide. According to its page, automatic updates from Nexus require Premium; manual download is free.
  • Vortex: Nexus’s general-purpose manager, compatible with Stardew Valley. Heads-up: the Ridgeside Village authors advise against installing their mod with Vortex or other managers; they recommend doing it by hand.
  • Nexus Mods App: Nexus’s new manager, open source and with a version for Linux and Steam Deck. Stardew Valley was its first fully supported game, with SMAPI diagnostics, and Nexus presents it as the future replacement for Vortex.

Once SMAPI is working, the next step is choosing what to install: check out our pick of the best Stardew Valley mods and the list of mods compatible with Stardew Valley 1.6. If you play with friends, read the multiplayer mods guide first, and if you play on mobile, the one on mods on Android and consoles.

A mod won’t load or the game crashes? Follow the guide with fixes for when mods aren’t working.

Frequently asked questions

Do I have to install SMAPI?

For almost every mod, yes: without SMAPI most of them won’t even load. Content Patcher and content packs need it too.

Will I lose my saves if I install SMAPI?

No. SMAPI runs alongside the normal game and you uninstall it with the same installer. That said, a save that uses content mods, like new NPCs, items or areas, can end up depending on them.

Can I add mods to a save I’ve already started?

UI mods, no problem. With expansions it depends: Stardew Valley Expanded recommends a new save, while Ridgeside Village has a progressive mode for existing saves since version 2.2.5.

Where is the Mods folder?

Inside the game folder. On Steam for Windows it’s at C:\Program Files (x86)\Steam\steamapps\common\Stardew Valley\Mods. If you can’t find it, use the show_game_files command in the SMAPI console.