How to Install Stardew Valley Mods on PC, Mac, Linux, Steam Deck, and Android

Written by: Editor In Chief
Published on:

Installing Stardew Valley mods usually means adding SMAPI, the community-built mod loader, then placing compatible mod folders in the game’s Mods directory.

The steps depend on your device, and a few checks before you download can save you from a broken launch or an incompatible save.

Before installing Stardew Valley mods

Back up your saves before changing game files.

On desktop, find the save folder through the Stardew Valley modding guide for your operating system, then copy it somewhere outside the game folder.

Mods can add features, change artwork, or alter gameplay, and most can be removed, but a mod that changes game data may affect a save after you uninstall it.

Check that the mod supports your Stardew Valley version and platform.

Read the mod’s description and requirements page, including any required framework mods.

Many current mods use SMAPI, while some visual or content changes depend on Content Patcher.

A mod may also require another mod to be installed first.

Use the official SMAPI website to download the mod loader, and use the Stardew Valley modding guide for platform-specific instructions.

Mod files are commonly hosted on Nexus Mods; check the page for the mod’s author, supported game version, installation notes, and updates.

How to install SMAPI on Windows

  1. Open the SMAPI website and download the latest stable version for Windows.
  2. Extract the downloaded archive.

    Open the extracted folder and run install on Windows.bat.

  3. Follow the installer prompts.

    If it does not find your game automatically, locate the folder containing Stardew Valley and choose it when prompted.

    The installer adds SMAPI and displays instructions for configuring the game launcher.

  4. If you use Steam, copy the launch option shown by the installer into Stardew Valley’s Steam launch options.

    In Steam, right-click the game, select Properties, and enter the provided command under Launch Options.

    For GOG or another launcher, follow the matching setup instructions on the Windows installation guide.

  5. Launch the game through your usual client.

    A SMAPI console window should open alongside the game.

Use the installer’s exact launch command.

Paths can vary if you chose a custom library or game folder, so copying a command from somebody else may point to the wrong location.

Installing mods after SMAPI

  1. Download a mod and read its installation instructions and requirements.
  2. Extract the mod archive.

    Most mods arrive as a folder containing a manifest.json file, sometimes with folders such as assets or i18n.

  3. Move the extracted mod folder into the Mods folder inside your Stardew Valley game folder.

    Do not leave it zipped, and avoid nesting it in extra folders.

    SMAPI should be able to find manifest.json without digging through multiple layers.

  4. Install any required framework mods the same way.

    Check each dependency’s own page for its latest version and requirements.

  5. Start Stardew Valley through SMAPI and watch the console during loading.

    SMAPI reports detected mods and flags many errors or outdated versions.

For example, a correctly extracted folder might look like Stardew Valley/Mods/ExampleMod/manifest.json.

A common mistake is ending up with Mods/ExampleMod/ExampleMod/manifest.json because the archive was unpacked into a folder that already contained another folder of the same name.

Installing mods on macOS and Linux

Download the matching SMAPI version for your operating system and follow the current steps on the official getting-started guide. macOS and Linux installers use different scripts and game paths from Windows, so do not run Windows instructions on those systems. macOS users should follow the full setup instructions, including any security prompts described in SMAPI’s guide.

After installation, add extracted mod folders to the game’s Mods directory as you would on Windows.

Configure your launcher to start the SMAPI executable or use the launch option provided by the installer.

The exact location depends on whether you installed the game through Steam, GOG, or another supported client, and whether you selected a custom library.

Can you install Stardew Valley mods on Steam Deck?

Yes.

Stardew Valley modding is supported on Steam Deck, but first check whether the game is running in native Linux mode or through Proton.

The installation path and launcher setup differ.

The Steam Deck SMAPI guide explains both routes and includes the relevant commands.

Follow the section for the mode selected in Steam’s game information.

Install the matching Linux or Windows version of SMAPI, then use the guide’s instructions to configure Stardew Valley’s launch options.

Add mod folders to the Mods directory identified by that setup.

Modding may increase power use, and a Windows-only dependency or unsupported mod may not work as expected on Deck.

Can you install mods on Android or consoles?

Android modding is possible through a separate, experimental SMAPI setup, and it does not use the desktop installation process.

The current guide lists prerequisites, including a 64-bit operating system and a supported game version; compatibility varies by mod.

Follow the steps in the Android SMAPI guide, which describes installing the launcher app, importing SMAPI, and adding mods to the Android Mods folder.

Do not assume a mod that works on PC will work on Android.

Check the mod page and Android guide, and make a save backup before experimenting. iOS and the console editions, including Nintendo Switch, PlayStation, and Xbox, do not support the standard SMAPI mod setup.

How to troubleshoot Stardew Valley mods

  • The game launches without mods: Confirm you started through SMAPI, not the regular game executable, and check that your launcher has the correct SMAPI path or launch option.
  • SMAPI cannot find a mod: Extract the archive and inspect its folder structure.

    Put the folder containing manifest.json directly inside Mods.

  • A mod is listed as outdated or incompatible: Check for an update that supports your current Stardew Valley version.

    Remove or update the affected mod before loading a save that depends on it.

  • A dependency is missing: Install the required framework or library mod, then restart the game.

    Check its own requirements in case it depends on another component.

  • The game crashes or behaves unexpectedly: Review the SMAPI console for the first error, then temporarily move the newest mod out of the Mods folder and launch again.

    Add mods back one at a time to identify a conflict.

  • The game updated recently: Give mod authors time to release compatible updates.

    Check the SMAPI compatibility notes and individual mod pages before reinstalling older files.

The official SMAPI troubleshooting guide explains how to locate the SMAPI log and share it when asking for help.

If a mod causes a problem, note your game version, platform, SMAPI version, and the first error message, then use the guide’s log instructions to provide useful details.

To add your first mod, install SMAPI for your device, extract one mod and its listed dependencies into Mods, then launch the game and confirm SMAPI reports that mod as loaded.