# SMAPI: the Stardew Valley mod loader that sits beside your game

> SMAPI is an open-source modding framework and API for Stardew Valley. It loads code mods, rewrites them for cross-platform compatibility, catches errors before they crash a save, and backs up saves daily.

**Pathoschild/SMAPI** — The modding API for Stardew Valley.

- Repository: https://github.com/Pathoschild/SMAPI
- Website: https://smapi.io/
- Stars: 2,739 · Forks: 345
- Language: C#
- License: LGPL-3.0
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/pathoschild-smapi

## The problem SMAPI solves for Stardew Valley players and modders

Stardew Valley ships without any way to load third-party code. Content edits can sometimes be done through asset replacement, but anything that adds behaviour, listens for events, or changes game logic needs code running inside the process. SMAPI is the piece that makes that possible. The README describes it as an open-source modding framework and API that lets you play the game with mods, installed safely alongside the game executable, and it states that it does not change any of your game files.

That last property matters more than it sounds. Because SMAPI sits next to the game rather than patching it, removing it is a matter of not launching through it, and your original installation stays intact. The audience splits in two. Players get a mod loader plus a set of safety nets: error interception, save fixes, update checks, and daily save backups through the bundled Save Backup mod. Modders get the API and event surface they build against, plus the compatibility rewriting described in the README, which means one compiled mod can work across the Windows, Linux and macOS builds of the game without the author handling each platform separately.

## What actually happens between launch and the title screen

The README lists seven purposes, and reading them in order gives you the startup sequence. SMAPI loads mods while the game is starting up, so mods can interact with it. Before loading them, it rewrites the mods' compiled code so they work on Linux, macOS and Windows without the mod needing to handle the differences between those game builds. In some cases that rewriting also repairs code broken by a game update, which is the mechanism behind mods that keep working after a patch they were never rebuilt for.

Once mods are running, SMAPI intercepts errors, prints the error information in the SMAPI console, and in most cases automatically recovers the game. The README frames the benefit plainly: this prevents mods from crashing the game and makes errors visible in the game itself instead of a generic program-has-stopped message. Separately, SMAPI detects outdated or broken code in mods and safely disables those mods before they cause problems, and it checks for new versions of installed mods and notifies you.

The save handling is the part worth understanding before you rely on it. SMAPI automatically fixes save data in some cases when a load would crash, for example when a custom location or NPC mod has been removed. That is a narrow repair, not a general undo. The daily backup, ten copies deep, comes from the bundled Save Backup mod rather than from the loader core, so the backup cadence is tied to that mod being present. The README does not document a rollback command for restoring a specific backup, so treat the ten files as something you locate yourself.

## Installing SMAPI and running your first mod

The README does not reproduce install commands. It points players at the player guide on the Stardew Valley wiki and modders at the documentation site at smapi.io/docs, and the repository ships a build directory alongside src, docs and the licence file. Get the installer from the player guide rather than from a mirror, since the guide is the path the project itself names.

The shape of an installed SMAPI is the same on every platform: a launcher that starts the game through the framework, and a mods folder the loader reads at startup. A mod is a folder inside that directory containing a manifest.json. The repository does not print a manifest example in the README, so the loader's expected mod layout is documented in the modding documentation at smapi.io/docs rather than here.

Drop the mod folder into the mods directory and start the game through the SMAPI launcher. What you should see is the SMAPI console window open alongside the game, listing each mod as it loads, and the title screen appear afterwards. If a mod is outdated or its code is broken, the console reports it and SMAPI disables that mod instead of letting it run, which is the compatibility check doing its job.

For a modder, the build side is documented separately in technical/mod-package.md, which covers the mod build configuration referenced from the README. The release notes file in the repository is where version 4.5.2 and the 4.5.x line are described.

## Where SMAPI is the wrong tool

SMAPI is a loader and an API, not a content pack. Installing it on a clean game with an empty mods folder gives you a console window and not much else. Players who want a specific feature, a new crop or a retexture, still need the mod that provides it, and that mod still has to be compatible with their game version.

The compatibility rewriting has limits that the README is honest about. It says SMAPI rewrites mods so they work across platforms, and that in some cases it also rewrites code broken by a game update. In some cases is doing real work in that sentence: a mod whose internals changed enough will not be repaired, and the loader will disable it rather than run it. The same applies to the save fixes, which the README scopes to some cases and gives removed custom locations or NPCs as the example.

There is also a platform question the README does not settle. The related searches around SMAPI on Android, a launcher APK, and a mobile version point at demand the README never addresses. The README describes installation alongside the game executable on Linux, macOS and Windows and says nothing about Android. Anyone searching for an APK is looking for something this repository does not document, and I would not treat the absence as a promise that a supported path exists.

## How SMAPI differs from a plain content patcher

The closest alternative in practice is a content-only modding approach, where mods replace or patch game assets and no third-party code runs in the process. The difference is not quality, it is what each can express. Asset replacement cannot add an event handler, cannot react to a player action at runtime, and cannot expose an API for other mods to call. SMAPI exists precisely because code mods are not possible without something to load them, as the README puts it.

Choosing between them is mostly about what you are shipping. A retexture or a data table edit is fine as content. Anything that needs to run logic, register events, or let a second mod build on top of it needs SMAPI. The trade-off you accept with SMAPI is a dependency chain: your mod now depends on the loader, on a compatible game version, and on the loader's compatibility rewriting continuing to cover whatever the game update changed. Content mods carry a shorter chain.

## Maintenance, upgrade cost and the LGPL-3.0 licence

The repository is not archived, and the last push was on 2026-09-22, six days before this writing, so the project is being worked on. The most recent release listed is 4.5.2 from 2026-03-22, with 4.5.0 and 4.5.1 both dated 2026-01-28. That gap between the March release and the September push tells you the default develop branch moves between tagged releases, which is normal for a project that also has to keep pace with game updates.

The upgrade cost falls mainly on modders, not players. A player updates SMAPI through the installer and the loader handles the rest, including disabling mods it finds broken. A modder has to track the release notes and the mod build configuration to know whether a change affects their build. The README also lists translation status per locale, with several languages only partly translated, so if you depend on localized SMAPI messages, check the table before assuming full coverage.

The licence is LGPL-3.0, and the repository carries LICENSE.txt at the top level. LGPL is a copyleft licence with a linking exception, which is why it is a common choice for a framework that other people's code loads against. I am not giving legal advice: if you plan to redistribute SMAPI inside a pack or link against it in a way you are unsure about, read LICENSE.txt and get your own answer.

## Conclusion

Adopt SMAPI if you want code mods in Stardew Valley on Windows, Linux or macOS, or if you are writing one and need the API surface and event system. Do not install it expecting it to add content on its own: it is a loader, and an empty mods folder changes nothing. Before you commit, check the player guide linked from the README, confirm your game version against the release notes for 4.5.2, and read the LGPL-3.0 licence text in LICENSE.txt if you plan to redistribute SMAPI alongside a mod pack.

## FAQ

### Do you need SMAPI to play Stardew Valley?

No. SMAPI is only needed if you want to run mods, and specifically code mods, which the README says are not possible without something to load them. A clean game plays fine without it.

### What is SMAPI used for?

SMAPI is a modding framework and API for Stardew Valley. It loads mods at startup, provides APIs and events for them, rewrites their compiled code for cross-platform compatibility, intercepts errors, checks for mod updates, and creates daily save backups.

### Is SMAPI safe to install?

The README states that SMAPI is safely installed alongside the game's executable and does not change any of your game files. It also creates a daily backup of your saves and keeps ten backups through the bundled Save Backup mod.

### How do I install SMAPI?

The README does not list install steps itself. It points players to the player guide on the Stardew Valley wiki and modders to the documentation at smapi.io/docs, and the repository ships a build directory alongside src.

### How do I use SMAPI with Steam?

The README does not describe a Steam-specific setup. It describes SMAPI as installed alongside the game executable and loading mods when the game starts, and it does not document a launch option or Steam configuration.

## Sources

- [License: LGPL-3.0](https://github.com/Pathoschild/SMAPI/blob/develop/LICENSE)
- [Pathoschild/SMAPI on GitHub](https://github.com/Pathoschild/SMAPI)
- [Project website](https://smapi.io/)
- [README](https://github.com/Pathoschild/SMAPI/blob/develop/README.md)
- [Releases](https://github.com/Pathoschild/SMAPI/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/pathoschild-smapi