How to Update Stardew Valley Mods Manually or With SMAPI

You fire up Stardew Valley after a major update, eager to check out the new content. But instead of the familiar title screen, you’re greeted by a wall of angry red text in a black console window. Your beloved farm is trapped behind a barrier of broken mods. This moment is a rite of passage for modded players, and learning how to update Stardew Valley mods is the key to getting back to your crops and friendships.
It’s a process that feels intimidating at first, but once you understand the rhythm, it becomes a simple, even satisfying, bit of digital housekeeping. This guide will walk you through every step, from essential backups to troubleshooting, turning you into a confident mod manager.

Table of Contents

At a Glance: The 5-Minute Mod Update Checklist

Pressed for time? Here are the absolute essentials for getting your mods running smoothly.

Back Up Your Save File: Before you do anything, copy your Saves folder to a safe place. This is your non-negotiable insurance policy.
Update SMAPI First: The mod loader itself needs to be on the latest version. Download it from smapi.io and run the installer.
Run the Game & Read the Console: Launch Stardew Valley through SMAPI. The console window will tell you exactly which mods are outdated (usually in purple text) and provide download links.
Delete, Then Replace: For each outdated mod, you must completely delete the old mod’s folder from your Mods directory before adding the new version. Do not just copy and paste over it.
Check Your Work: Relaunch the game. If the console is free of red or purple error messages, you’re ready to play.

Before You Touch a Single File: The Golden Rules of Modding

Before diving into your Mods folder, a little prep work can save you from a world of frustration. Think of these two rules as the foundation of a stable, happily modded game.

Rule #1: Always Back Up Your Save Files

If you take only one piece of advice from this guide, let it be this: back up your saves. A mod update gone wrong or a corrupted file can potentially damage a save file you’ve poured hundreds of hours into. It’s rare, but the risk is not worth it.
How to Manually Back Up Your Saves:

Close Stardew Valley completely.
Navigate to your game’s save folder.

Windows: %AppData%\StardewValley\Saves (You can paste this directly into your File Explorer’s address bar.)
macOS & Linux: ~/.config/StardewValley/Saves

Copy the entire Saves folder and paste it somewhere safe, like your Desktop or a cloud storage folder. It’s helpful to rename the copied folder with the date, like Stardew Saves Backup - 2024-03-21.
Thankfully, SMAPI provides its own safety net. It automatically creates a backup of your save file once per day in the Stardew Valley/Mods/SaveBackup folder. This is a fantastic fallback, but a manual backup before a big modding session is still the wisest move.

Rule #2: Make Sure Stardew Valley Itself is Updated

Mods are designed to work with a specific version of the game. Trying to run a mod built for Stardew Valley 1.6 on a 1.5.6 version of the game (or vice-versa) is a recipe for crashes.
Before you update your mods, ensure the base game is current.

On Steam: Your game should update automatically. You can verify by right-clicking Stardew Valley in your library, selecting “Properties,” and checking the “Updates” tab.
On GOG: Use the GOG Galaxy client to check for and apply any available game updates.
With a fresh backup and an updated game, you’re ready to tackle the mods themselves.

Your Best Friend for Modding: Understanding the SMAPI Console

When you launch modded Stardew Valley, that black window filled with text that pops up isn’t an error—it’s your command center. This is the SMAPI (Stardew Valley Modding API) console, and it’s the most powerful tool you have.
Closing it will close the game. Instead, you need to learn to read it. SMAPI scans your Mods folder on every launch and gives you a live report. It uses a simple color-coded system to tell you what’s going on.

Purple Text: This is SMAPI’s friendly nudge. It means a mod has a new version available. In most cases, SMAPI will even provide a direct link to the Nexus Mods page where you can download the update. This is your primary “to-do” list.
Gray Text: This indicates a mod that SMAPI can’t automatically check for updates. This doesn’t mean it’s broken, just that you’ll need to manually visit its mod page to see if a newer version exists.
Red Text: Pay attention to this. Red means there’s a serious problem. The mod might be completely incompatible with the new game version, missing a required dependency (another mod it needs to function), or improperly installed. These mods will not load and often need to be removed or replaced.
Your goal after an update is a clean SMAPI launch—a console window with no purple or red text related to your mods.

The Step-by-Step Guide to Manually Updating Your Mods

This manual method is the most reliable way to ensure a clean and stable update. It gives you full control and helps you understand how your mods folder is structured.

Step 1: Update SMAPI First

Before you can trust its reports, you need to make sure the mod loader itself is up-to-date.

Go to the official SMAPI website at smapi.io.
Download the latest version.
Unzip the downloaded file and run the installer for your operating system (install on Windows.batch, install on macOS.command, or install on Linux.sh).
The installer will automatically find your game directory and update SMAPI for you. It’s the exact same process you used to install it the first time.

Step 2: Launch the Game to Generate a Mod Report

With the latest SMAPI installed, run Stardew Valley. Don’t click past the console window—this is where you gather your intel. Watch as SMAPI lists your mods. Take a screenshot, or copy and paste the purple-text sections into a notepad. This is your shopping list.

Step 3: Download the Latest Mod Versions

Using the links from the SMAPI console or by navigating to Nexus Mods yourself, find the page for each outdated mod. Go to the “Files” tab and download the main, most recent version.

Pro Tip: While you’re on the mod page, skim the description or the “Posts” section. The mod author might have included special instructions for updating, especially after a major game patch like 1.6.

Step 4: The Most Important Step: Delete the Old Mod Folder

This is the step where most players make a mistake. Do not just drag the new files on top of the old ones. This can leave behind outdated files that will conflict with the new code and cause bizarre, hard-to-diagnose bugs.
You must completely delete the old version.

Navigate to your Stardew Valley/Mods folder.
Find the folder for the mod you are updating (e.g., [CP] Seasonal Outfits).
Select the folder and delete it. Send it to the Recycle Bin/Trash.
This clean slate is essential for a stable game. In fact, learning this single step is the core of understanding [placeholder_link slug=”how-to-update-stardew-mods” text=”how to update Stardew mods”] correctly.

Step 5: Install the New Mod Version

Now, find the new mod version you downloaded in Step 3.

It will almost always be a .zip file. Unzip it.
Inside, you’ll find a folder with the mod’s name.
Drag this single folder into your Stardew Valley/Mods directory.

Pitfall to Avoid: The “Double Folder” Mistake
A common error is accidentally nesting the mod folder. Make sure the folder containing the manifest.json file is the one in your Mods directory.

Correct: .../Mods/[CP] AwesomeMod/manifest.json

Incorrect: .../Mods/[CP] AwesomeMod-1234-v2/[CP] AwesomeMod/manifest.json

Step 6: Relaunch and Verify

Repeat steps 3-5 for all your outdated mods. Once you’re done, launch Stardew Valley through SMAPI again.
Watch the console window closely. If all you see is black, white, and gray text (with no red or purple errors), congratulations! You’ve successfully updated your mods. Load up your save file and make sure everything in-game is working as you expect.

How to Keep Your Custom Settings (The `config.json` Trick)

Many mods have a config.json file inside their folder that stores your personal preferences—like changing a keybinding or toggling a feature. Deleting the whole mod folder means deleting this file, too. Here’s how to preserve your settings:

Before deleting the old mod folder, open it and find the config.json file.
Copy that file and paste it somewhere safe, like your Desktop.
Now, delete the entire old mod folder as instructed.
Install the new, updated mod folder.
Finally, copy your saved config.json file and paste it into the new mod’s folder, overwriting the default one that was just created.
Your custom settings will now be applied to the updated mod.

When Things Go Wrong: Common Problems and How to Fix Them

How to update Stardew Valley mods: step-by-step guide for seamless gameplay.

Sometimes, even when you follow the steps perfectly, things break. Don’s panic. Here’s how to diagnose and fix the most common issues.

Crashing on Startup or a Blank Screen

This usually points to a critical incompatibility. It’s often caused by a core framework mod (like Content Patcher or Farm Type Manager) being severely outdated, or SMAPI itself not being updated after a major game patch. Double-check that you’ve updated SMAPI first, then re-check all of your framework mods.

SMAPI Says a Mod is “Broken” or “Incompatible”

If you get a red-text error for a mod you just updated, it could be a few things:

You downloaded the wrong version: Some mods have separate files for Stardew 1.5 and 1.6. Make sure you grabbed the right one.
The mod is truly broken: After a big game update, some mods are simply abandoned by their authors and will not work. You’ll have to remove it and wait for a new, unofficial update from another modder or find a replacement.
A missing dependency: The mod needs another mod to work, and you either don’t have it or its dependency is also outdated. Read the mod’s Nexus page carefully for any listed requirements.

Parsing Your SMAPI Log for Clues

When your game crashes or has a serious error, SMAPI generates a detailed log file. This log is the key to getting help from the community.

Find your log file at %AppData%/StardewValley/ErrorLogs/smapi-latest.txt.
Go to the official log parser website: smapi.io/log.
Follow the instructions on the page to copy and paste the entire contents of your log file.
The site will analyze your log, explain the errors in plain language, and often suggest concrete steps to fix them. If you ever need to ask for help on a forum or Discord, sharing the link to your parsed log is the best way to get a quick and accurate answer.

Can You Automate This? Exploring Mod Updaters

If managing a list of 100+ mods manually sounds like a chore, you might be interested in a more automated approach. Mods like “Mod Update Menu” can help streamline the process.
These mods typically add a new menu to your game that checks for updates and, in some cases, can download and install them for you.

Pros: Extremely convenient, especially for large mod lists. It saves you from having to visit dozens of Nexus pages.
Cons: They aren’t foolproof. They may not work for mods hosted off of Nexus or for mods that require special installation steps. You lose a degree of control, and it’s still good practice to understand the manual method in case something goes wrong.
Our Recommendation: Start with the manual method to learn the fundamentals. Once you’re comfortable, an updater mod can be a great time-saver for routine updates.

Frequently Asked Questions About Updating Stardew Mods

Do I have to update every single mod after a game patch?

For major game updates (like 1.5 to 1.6), you should assume that yes, almost every mod will need a corresponding update. For minor bug-fix patches from ConcernedApe, many mods (especially simple ones) will continue to work fine. SMAPI is your guide here—if it doesn’t flag a mod in purple, you can usually leave it be.

What if a mod I love hasn’t been updated?

First, check the mod’s “Posts” or “Bugs” section on Nexus Mods. The author may have given a status update, or other users might have found a temporary fix. Sometimes, the community will release an unofficial, temporary patch to tide players over. If not, your only option is to remove the mod from your Mods folder and play without it until an official update is released.

Can I just overwrite the old files instead of deleting the folder?

You really shouldn’t. We’ve said it before, but it’s the number one cause of weird, “ghost” bugs. An old script or asset file left behind can wreak havoc on a new version. Always delete the entire old folder for a perfectly clean installation.

Will updating my mods mess up my save file?

Updating a mod to a new version is generally very safe for your save file. The risk comes from removing a mod, especially one that adds items, NPCs, or new locations. If you remove a mod that gave you an item, that item will simply disappear. But if you remove a mod that adds a new map area while you are standing in it, your save could become unloadable. This is precisely why Rule #1 is to always back up your save file.

Your Updated Farm Awaits

With a clean console and a fully updated mod list, you’ve successfully navigated one of the trickiest parts of the Stardew Valley modding experience. You’re not just a farmer anymore; you’re a capable mod manager. By following these steps—backing up your data, reading the SMAPI console, and doing a clean reinstall of each mod—you’ve set yourself up for a stable and enjoyable game.
Now go on, get back to Pelican Town. Those ancient fruits aren’t going to turn themselves into wine.

Author
Recent Posts

Yaride Tsuga

Yaride Tsuga, known widely by his gaming pseudonym, is a passionate gamer and aspiring technical guide writer with a mission to simplify gaming for enthusiasts worldwide. From a young age, Yaride immersed himself in the digital realms of consoles, PCs, and mobile games, cultivating a deep understanding of both mainstream and niche titles. Over the years, his curiosity evolved beyond gameplay into solving technical challenges—whether fixing bugs, optimizing performance, or troubleshooting glitches—that often hinder the gaming experience.

How to Update Stardew Valley Mods Manually or With SMAPI

At a Glance: The 5-Minute Mod Update Checklist