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. It's a cool pufferchick.

Get help

What's new in...

SMAPI 2.5.5?

SMAPI 2.5 mainly...

  • Adds support for content packs.
    Content packs are collections of files for a SMAPI mod to load. These can be installed directly under Mods like a normal SMAPI mod, get automatic update and compatibility checks, and provide convenient APIs to the mods that read them. (Existing content packs for some mods will need an update to work this way.)
  • Adds mod detection for unhandled errors (so most errors now mention which mod caused them).
  • Adds install scripts for Linux/Mac (no more manual terminal commands!).
  • Adds the missing mod's name and URL to dependency errors.
  • And includes various other fixes and improvements.

Minor releases:

  • 2.5.1 fixes an event error in rare cases with SMAPI 2.5.
  • 2.5.2 fixes an issue with mod asset changes not taking effect and fixes the log parser being blank in some cases.
  • 2.5.3 includes several fixes, improved compatibility and update checks, and internal changes to support the upcoming Stardew Valley 1.3 beta.
  • 2.5.4 improves the content API to support newer mods like Content Patcher, and makes internal changes to support the upcoming Stardew Valley 1.3 beta.
  • 2.5.5 fixes various bugs and errors, and makes internal changes for the upcoming Stardew Valley 1.3 beta.

Requires Stardew Valley 1.2.30+ on Linux/Mac/Windows. Compatible with most mods for SMAPI 0.40+.

See the release notes and mod compatibility list for more info.

SMAPI 2.6-beta.21?

SMAPI 2.6 is a huge update (with over 300 commits). There are too many changes to list here, but here are the main highlights for players:

  • updated for Stardew Valley 1.3 beta;
  • added save backups;
  • significantly improved SMAPI's update checks (including support for optional and unofficial updates);
  • fixed default color scheme on Mac;
  • many bug fixes (including SEHException errors for some players);
  • updated compatibility list.

And for modders:

  • added an input API for reading and suppressing keyboard/controller/mouse input;
  • added support for custom seasonal map tilesheets;
  • added support for intercepting assets loaded by temporary content managers;
  • added prototype SMAPI 3.0 events;
  • added a prototype mod handler toolkit for external tools;
  • added code analysis to flag common issues as build warnings;
  • added support for reloading NPC schedules through the content API;
  • many changes to support multiplayer.


  • Players: some mods haven't been updated for Stardew Valley 1.3 yet. See the mod compatibility list for the latest updates and fixes.
  • Modders: Stardew Valley 1.3 has significant changes. See the migration guide.

Beta release notes:

  • beta 2:
    • Fixed installer not copying needed file.
  • beta 3:
    • Fixed game freeze on shipping menu.
    • Fixed farmhand crash if the host quits while they're still on the character creation screen.
    • Fixed load-save error when starting the game in non-English.
  • beta 4:
    • Added prompt when using an old SMAPI beta.
    • Added for modders: Constants.TargetPlatform and semanticVersion.IsPrerelease().
    • Fixed Linux/Mac installer errors for some players.
    • Fixed log parser not correctly parsing content packs with no description.
    • Disabled some broken mod versions.
  • beta 5:
    • Fixed installer error for Windows users.
  • beta 6–7 were internal releases.
  • beta 8:
    • Forced game to load the save synchronously.
    • Rewrote location events so they make sense in multiplayer and provide more flexible data.
    • Added more location events.
    • Added helper.Multiplayer.GetActiveLocations() for modders.
    • Enforced mod ID format restrictions.
    • Fixed errors if mod loads a PNG tilesheet when game is loading.
    • Fixed input suppression not working in some cases.
    • Fixed mod changes to fence sprites not being applied.
    • Fixed Linux/Mac installer errors for some users.
  • beta 9–11 were internal releases.
  • beta 12:
    • Rewrote content API to fix various texture issues (eye color swaps, mangled clothing colors, etc) and fix wedding ring recipe disappearing.
    • Fixed installer console colors on Mac.
    • Fixed content cache always missed when not playing in English.
    • Fixed errors when horses, NPCs, or children have certain characters in their name.
    • Fixed link in installer not linking to a useful page.
    • Renamed install.exe to install on Windows.exe to avoid confusion.
    • Added helper.Multiplayer.GetActiveLocations() for modders.
  • beta 13:
    • Added a default save backup mod.
    • Improved how mod issues are displayed in the console.
    • Tweaked 'outdated' error text to avoid confusion.
    • Fixed world_setseason command not applying the game's season change logic.
    • Fixed log parser error with some newer logs.
    • Updated compatibility list.
  • beta 14:
    • Updated for Stardew Valley 1.3.11.
    • Fixed compatibility issue on Windows for certain mods compiled on Linux/Mac.
    • Fixed bundled SaveBackup mod replacing Omegasis' SaveBackup mod. (That mod now gets renamed to AdvancedSaveBackup per discussion with Omegasis.)
    • Fixed bundled SaveBackup mod including unnecessary files.
  • beta 15:
    • Fixed content load errors in some cases.
    • Fixed launch issue for Linux players using some terminals. (Thanks to HanFox and kurumushi!)
    • Fixed SaveBackup mod failing on Mac.
    • Fixed slower startup times on Windows due to mods being rewritten unnecessarily.
    • Fixed issue where mods could intercept other mods' assets, or indirectly affect other mods' data through a shared cache.
    • For modders:
      • Rewrote content core.
      • Added option to suppress update checks for a specific mod in StardewModdingAPI.config.json.
      • Hid more game debug output from the console and log.
      • Tweaked context trace messages to make multiplayer context more clear.
      • Fixed some common non-mod build output being included in release zip.
      • Fixed input suppression not working on the title menu.
      • Fixed debugging issues on Windows.
  • beta 16:
    • For players:
      • Fixed installer not finding game path in some cases.
      • Fixed installer showing duplicate game paths in some cases.
      • Fixed installer not removing some SMAPI files.
      • Fixed Nexus mod update alerts not showing HTTPS links.
      • Fixed issue where a mod crashing in CanEdit or CanLoad could cause an abort-retry loop.
      • Fixed error when a mod loads an unpacked .tbin map that references custom seasonal tilesheets.
      • Updated compatibility list.
    • For the log parser:
      • Redesigned upload page to make it more intuitive for new players.
      • Changed filters to show DEBUG messages by default.
      • Fixed mangled crossplatform paths in some cases.
    • For modders:
      • Added input API for reading and suppressing keyboard, controller, and mouse input.
      • Added support for launching multiple instances transparently. This removes the former --log-path command-line argument.
      • Added Harmony DLL for internal use by SMAPI. (Mods should still include their own copy for backwards compatibility, and in case it's removed later. SMAPI will always load its own version though.)
      • Added the first SMAPI 3.0 events. These are much more powerful, consistent, and discoverable than the existing events. However they're preview-only, not officially documented, and may change without warning.
      • Added latest mod file version (including optional files) to Nexus API results.
      • Fixed assets not being cloned when transferred between content managers in some cases.
    • For SMAPI developers:
      • Added prototype SMAPI 3.0 events accessible via helper.Events.
      • Added prototype mod handler toolkit.
      • Added Harmony for SMAPI's internal use to patch game functions for events.
  • beta 17:
    • For players:
      • Added update checks for optional files on Nexus.
      • Fixed SEHException errors and performance issues in some cases.
      • Fixed error when a mod has no manifest.
      • Fixed error when patches are applied before SMAPI checks for minimum compatibility.
      • Fixed world_setseason command not normalising the season value.
      • Fixed player_add name not using exact match if there are also fuzzy matches.
      • Fixed ConsoleCommands error in Stardew Valley 1.3.20.
      • Updated compatibility list.
    • Web UI:
      • Added option to download from Nexus.
      • Pufferchick is now HD.
      • Improved layout on small screens.
    • For modders:
      • Added absolute pixels to ICursorPosition.
      • Added another prototype SMAPI 3.0 event (helper.Events.World.DebrisListChanged).
      • Update checks now use the update key order when deciding which to link to.
      • Fixed SemanticVersion allowing invalid versions in some cases.
      • Fixed input events' e.Cursor showing wrong tile if the player moves without moving the on-screen cursor.
    • For SMAPI developers:
      • Added metadata dump option in StardewModdingAPI.config.json for troubleshooting some cases.
      • Rewrote update checks to move most logic into the API, support optional mod versions, and support future lookups by mod ID.
  • beta 18:
    • For players:
      • Improved startup performance and memory usage in some cases.
      • Fixed tilesheets not updating for season transition.
      • Fixed list_items and player_add commands not handling secret notes.
    • For modders:
      • Updated NuGet package:
        • Added reference to new SMAPI DLL.
        • Added option to ignore custom files by regex.
        • Note: you need to update the package to compile your mods against beta 18 and later. Released mods should still work fine since SMAPI will rewrite them.
      • Fixed input API not available through the mod helpers.
    • For SMAPI developers:
      • Added StardewModdingAPI.Toolkit.CoreInterfaces assembly for toolkit interfaces available to SMAPI mods.
      • Updated to Mono.Cecil 0.10 and updated other packages.
  • beta 19:
    • For players:
      • Added update alerts for incompatible mods with an unofficial update on the wiki.
      • Fixed update checks failing when some mods don't have a mod ID.
      • Fixed many mods failing if the player name is blank.
      • Fixed repeated errors in some cases when a mod references a missing assembly.
      • Fixed AssemblyResolutionException errors in rare cases.
      • Removed the player_setlevel and player_setspeed commands, which weren't implemented in a useful way. Use a mod like CJB Cheats Menu if you need those.
    • For modders:
      • Added support for reloading NPC schedules through the content API.
      • Added support for reading/writing ISemanticVersion to JSON.
      • Added log parser option to view raw log.
      • Fixed Context.IsPlayerFree being false during festivals.
      • Fixed SaveEvents.AfterReturnToTitle event not triggered after a multiplayer disconnect.
      • Fixed some mods getting rewritten unnecessarily in beta 18 and breaking debuggers.
    • For SMAPI developers:
      • Further development for the upcoming mod handler toolkit.
  • beta 19.1:
    • Fixed all mods failing if any mod has no manifest.
  • beta 20:
    • For players:
      • Fixed game freeze if the window loses focus while loading.
      • Fixed crash on season change with mods that load PNG tilesheets.
      • Fixed error if a mod translation file is empty.
      • Fixed mods being marked incompatible if they reference certain types (only known to affect MTN).
    • For modders:
      • Added compatibility checks for Netcode changes.
      • Added compatibility checks for broken constructor references.
      • Added prototype helper.Events.GameLoop events for SMAPI 3.0.
  • beta 20.1:
    • Fixed installer missing some files.
    • Fixed installer removing SaveBackup's config.json and previous backups.
  • beta 21:
    • Added friendlier error when using SMAPI 2.6 with Stardew Valley 1.2.
    • Fixed mods marked incompatible on Linux/Mac if they reference Microsoft.Xna.Framework.Xact.
    • Fixed console commands being invoked asynchronously.
    • Updated compatibility list.

Requires Stardew Valley 1.3.25 beta or later on Linux/Mac/Windows.

See the release notes and mod compatibility list for more info.

SMAPI is an open-source project by Pathoschild. It will always be free, but donations are much appreciated to help pay for development, server hosting, domain fees, coffee, etc.

Special thanks to acerbicon, ChefRude, cheesysteak, hawkfalcon, jwdred, KNakamura, Kono Tyran, Robby LaFarge, and a few anonymous users for their ongoing support; you're awesome! 🏅

For mod creators