How To Update Stardew Mods And Keep Your Game Running Smoothly

When a new Stardew Valley patch drops, the excitement is often followed by a wave of anxiety for mod users. Suddenly, that carefully curated farm life is at risk, and learning how to update stardew mods correctly becomes less of a chore and more of a critical mission to prevent crashes, errors, and heartbreak. It’s not just about getting the latest features from mod authors; it’s about maintaining the stability of your game and ensuring your save file, with its hundreds of hours of work, remains safe and sound.
This guide goes deep into the specific process of updating, moving beyond the basics to give you the expert-level workflow that seasoned players use to keep their games running flawlessly, update after update.

Table of Contents

At a Glance: Your Mod Update Cheat Sheet

Get up to speed with the key takeaways for a successful mod update every time:

The Golden Rule: Always back up your save files before you touch a single mod. No exceptions.
SMAPI is Your Co-pilot: Your SMAPI console window is your number one diagnostic tool. It will tell you exactly which mods are outdated, often with direct links to download the new versions.
The “Clean Install” Principle: Never overwrite old mod files. Always completely delete the old mod’s folder before installing the new version to prevent file conflicts.
Save Your Settings: Your custom configurations are stored in a config.json file. Learn how to preserve it so you don’t have to reconfigure everything after an update.
When in Doubt, Parse Your Log: If your game crashes or acts weird after an update, the smapi.io/log parser is the fastest way to find out exactly what went wrong.

Before You Touch a Single Mod: The Non-Negotiable Prep Work

Jumping straight into updating mods without preparation is like sailing into a storm without checking the weather. A few minutes of prep work can save you hours of troubleshooting later.

Backup Your Save Files: The Ultimate Safety Net

This is the single most important step. A buggy mod update can, in rare cases, corrupt a save file. A backup ensures you can always roll back to a working state.

Locate your saves folder. It’s in a different location than the game itself.

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

Copy the entire Saves folder to a safe location, like your Desktop or a cloud storage folder. Give it a clear name, like “Stardew Saves Backup – Pre 1.6.4 Update.”
SMAPI also creates its own automatic backups in a Mods/SaveBackup folder inside your game directory. This is a great secondary safety net, but a manual backup that you control is always the best practice.

Update the Foundation First: Stardew Valley & SMAPI

Mods are built to run on specific versions of the game and the Stardew Modding API (SMAPI). Trying to run a new mod on an old foundation is a recipe for disaster.

Update Stardew Valley: Let Steam, GOG, or your game client update the base game to the latest version first. You can see your game version on the bottom-right of the title screen.
Update SMAPI: Download the latest stable version from smapi.io. Unzip the file and run the installer for your operating system (install on Windows.exe, install on Mac.command, etc.). The installer will automatically find your game and update SMAPI for you. Launch the game once to confirm the new SMAPI version appears at the top of the console window.
With a fresh game version and the latest SMAPI, you now have a stable platform to begin updating your individual mods.

Let SMAPI Do the Heavy Lifting: Reading the Console for Clues

Essential prep work: non-negotiable steps before installing game mods for smooth gameplay.

Your most powerful tool in the update process is the SMAPI console itself—that text window that pops up when you launch the game. Don’t just ignore it; it’s your personal update assistant.
When you launch Stardew Valley with mods, SMAPI performs a check on every single one. If a mod has a known update, SMAPI will flag it for you, usually in purple text.
Here’s a typical scenario:

[SMAPI] Stardew Valley Expanded 1.14.23 by FlashShifter - SKIPPED: this mod is no longer compatible. Please update it.
[SMAPI] You can update it from https://www.nexusmods.com/stardewvalley/mods/3753
SMAPI has not only identified an outdated mod but has also given you the exact link to download the new version. This eliminates the guesswork of checking dozens of mod pages manually. This SMAPI-first approach is a cornerstone of the general process to Update your Stardew Valley mods and turns a daunting task into a simple to-do list. Work your way through the SMAPI list, updating each flagged mod one by one using the manual method below.

The Manual Update Playbook: The “Delete, Then Replace” Method

Once SMAPI has told you which mods to update (or if you’re checking them manually), follow this precise, “clean install” process. This is the most reliable way to prevent errors caused by leftover files.

Step 1: Download the New Mod Version

Navigate to the mod’s page on Nexus Mods, ModDrop, or GitHub. Before downloading, check two things on the mod page:

Requirements: Does the mod require a specific version of SMAPI or other mods (often called dependencies)? Make sure you have them.
Compatibility: Read the description or posts section for any notes about compatibility with the latest Stardew Valley patch.
Download the main file. It will usually be a .zip archive.

Step 2: Preserve Your Custom Settings (The `config.json` Trick)

Most configurable mods store your personal settings in a file named config.json inside that mod’s folder. If you just delete the old folder, you’ll lose these settings.

Navigate to your Stardew Valley/Mods folder.
Open the folder of the mod you are about to update (e.g., [CP] Stardew Valley Expanded).
Find the config.json file.
Copy this file and paste it somewhere safe, like your Desktop.

Step 3: Delete the ENTIRE Old Mod Folder

This is the most critical step. Do not simply drag the new files and drop them on top of the old folder to “overwrite” them. This can leave behind old, unused files that can conflict with the new version and cause bizarre, hard-to-diagnose bugs.
In your Mods folder, select the folder for the mod you’re updating and delete it completely.

Step 4: Install the New Mod and Restore Your Settings

Unzip the new mod version you downloaded in Step 1.
Move the new, unzipped mod folder into your Stardew Valley/Mods directory.
Take the config.json file you saved to your Desktop and move it into this new mod folder. Windows or your OS will ask if you want to replace the file. Say yes.
Your mod is now updated with your custom settings intact. Repeat this process for all mods that need an update.
| Step | Action | Why It’s Important |
| :———————— | :————————————————————————————————- | :—————————————————————————————– |
| 1. Backup config.json | Copy the config.json file from the old mod folder to a safe place (like your Desktop). | Preserves your custom settings so you don’t have to reconfigure the mod from scratch. |
| 2. Delete Old Folder | Select the entire folder of the outdated mod inside your Mods directory and delete it. | Guarantees a clean install and prevents old, conflicting files from causing errors. |
| 3. Install New Folder | Unzip the downloaded update and move the new mod folder into your Mods directory. | Installs the latest version of the mod’s files. |
| 4. Restore config.json | Move your saved config.json file back into the newly installed mod folder, replacing the default. | Applies your saved settings to the new version. |

Troubleshooting Post-Update Glitches

SMAPI reads console output, providing crucial clues for game troubleshooting.

Even with a perfect process, things can go wrong. A mod might have a hidden bug, or a conflict with another mod might arise. Your primary tool for solving these issues is the SMAPI log.
After your game crashes or you encounter a bug, don’t just restart. Find the log SMAPI generated.

Find your log: A file named smapi-latest.txt is located in your main Stardew Valley game folder.
Don’t try to read it yourself: The raw log can be confusing. The creators of SMAPI have built an amazing tool to help.
Use the log parser: Go to smapi.io/log in your web browser. Follow the instructions on the page to upload or paste the entire contents of your smapi-latest.txt file.
The website will analyze your log and provide a clear, color-coded report that often tells you the exact problem. It might say a mod is missing a required dependency, a file is corrupted, or two mods are conflicting. This parsed log is the key to getting fast, effective help from the modding community.

Quick Questions, Expert Answers

Here are some common sticking points and misconceptions about updating Stardew Valley mods.

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

A: You shouldn’t. While it might work sometimes, it’s a huge gamble. If a mod author renamed or removed a file in the new version, your old file will be left behind as a “ghost” file. This can lead to double-loading assets, game-breaking errors, or subtle bugs you won’t notice for hours. The “delete, then replace” method is the only way to guarantee a clean installation.

Q: My `config.json` settings didn’t work after I copied the file over. What happened?

A: This can happen if the mod author significantly changed the configuration options between versions. The structure of your old config.json may no longer be valid. The best solution is to let the new mod generate a fresh config.json (by running the game once), then open both your old and the new config file side-by-side in a text editor and manually transfer your settings over.

Q: SMAPI says a mod is broken or incompatible, but there’s no update for it. Now what?

A: This is common right after a major game patch like 1.6. It means the mod author hasn’t released a compatible version yet. You have two choices:

Be Patient: Temporarily remove the mod’s folder from your Mods directory and wait for the author to publish an update. Check the mod’s page on Nexus for updates.
Check for Unofficial Patches: Visit the “Posts” or “Bugs” section on the mod’s Nexus Mods page. Sometimes other community members or the author will post temporary fixes or instructions to get the mod working.

Q: What about mod managers like Stardrop or Vortex?

A: Mod managers can simplify the process by automating downloads and installations, especially if you have a large number of mods from a single source like Nexus Mods. However, they are just tools that follow a similar process. Understanding the manual “delete and replace” method is crucial because it empowers you to fix problems when the manager fails or when you use mods from sources that managers don’t support.

Your Go-Forward Plan for Smooth Mod Updates

Updating mods doesn’t have to be a source of stress. By turning it into a disciplined, step-by-step routine, you can keep your game stable and spend less time troubleshooting and more time playing.
Here is your final checklist for every update cycle:

[ ] 1. Pre-Flight Check: Backup your entire Saves folder to a safe location.
[ ] 2. Update the Foundation: Ensure Stardew Valley and SMAPI are fully updated.
[ ] 3. Run Diagnostics: Launch the game once and read the SMAPI console for the list of outdated mods.
[ ] 4. Execute the “Clean Install”: For each outdated mod, perform the four-step process:
Save the config.json.
Delete the old folder.
Install the new folder.
Restore the config.json.
[ ] 5. Test Flight: Launch the game and load your save to ensure everything works as expected.
[ ] 6. Troubleshoot if Needed: If you encounter errors, immediately go to smapi.io/log and parse your latest log for answers.
By internalizing this workflow, you’ll be able to handle any Stardew Valley update with confidence, keeping your modded paradise running smoothly for years to come.

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.