Installation Guide

Follow these steps to install Content Patcher
and start using content packs.

SMAPI

  1. Install SMAPI first.
  2. Download Content Patcher from this site.
  3. Place it in your Mods folder.
  4. Add your content packs.

Make sure you’re using Stardew Valley 1.6 or higher.

SMAPI is the mod loader for Stardew Valley. Download the latest SMAPI installer from its official source, unzip it and run the installer for your system (install on Windows.bat, install on macOS.command or install on Linux.sh). From then on, start the game through SMAPI so your mods load.

Install Content Patcher on Stardew Valley 1.6

This Stardew Valley Content Patcher guide takes you from a clean game to your first content pack. It works on Windows, macOS and Linux (including Steam Deck), and the setup takes about five minutes:

  1. Update the game to the latest 1.6 version and start it once without mods.
  2. Install the latest Stardew Valley SMAPI release (the Stardew Modding API). Version 4.0 or later is required for 1.6.
  3. Open the Download page, get Content Patcher and unzip the archive.
  4. Move the ContentPatcher folder into Stardew Valley/Mods.
  5. Unzip each content pack into the same Mods folder (pack folders often start with [CP]).
  6. Launch the game through SMAPI. The console lists Content Patcher and every pack it loaded; red lines are errors.

Where is the Mods folder? SMAPI creates it in your game folder. Steam defaults: Windows C:\Program Files (x86)\Steam\steamapps\common\Stardew Valley\Mods, macOS ~/Library/Application Support/Steam/steamapps/common/Stardew Valley/Contents/MacOS/Mods, Linux ~/.local/share/Steam/steamapps/common/Stardew Valley/Mods.

How to use Content Patcher: the basic structure of a content pack

This mini Content Patcher tutorial builds a working pack from three files. A content pack is a folder inside Mods with two required files: manifest.json tells SMAPI what the pack is, and content.json tells Content Patcher what to change. Images and other files usually go into an assets subfolder.

manifest.json

manifest.json
{
  "Name": "My First Pack",
  "Author": "Your Name",
  "Version": "1.0.0",
  "Description": "New portrait and dialogue for Abigail.",
  "UniqueID": "YourName.MyFirstPack",
  "ContentPackFor": {
    "UniqueID": "Pathoschild.ContentPatcher"
  }
}
UniqueID
A unique ID for your pack, usually YourName.PackName. Two mods with the same ID can’t be loaded together.
Version
Your pack’s own version. Raise it whenever you publish an update.
ContentPackFor
Tells SMAPI that this folder is a content pack for Content Patcher. Copy this block exactly; it is Content Patcher’s mod ID.

content.json

content.json
{
  "Format": "2.0.0",
  "Changes": [
    {
      "Action": "EditImage",
      "Target": "Portraits/Abigail",
      "FromFile": "assets/abigail.png"
    },
    {
      "Action": "EditData",
      "Target": "Characters/Dialogue/Abigail",
      "Entries": {
        "Mon": "Hey, @! Want to explore the mines later?"
      }
    },
    {
      "Action": "Load",
      "Target": "Animals/White Chicken",
      "FromFile": "assets/white-chicken.png",
      "When": {
        "Season": "Winter"
      }
    }
  ]
}
Format
The Content Patcher format version the pack was written for. It is not your pack’s version.
Changes
The list of patches. Each patch has an Action and a Target (the game asset to change).
When
Optional conditions. The last patch above only applies in winter. See tokens & conditions.

In dialogue, @ is replaced with the player’s name. Save both files as UTF-8 plain text; JSON is strict about commas and quotes, so a missing comma is the most common reason a pack fails to load.

Patch actions you’ll use most

Think of this section as short Content Patcher documentation for the five actions that cover most packs:

Load
Replaces a whole asset with your file. Only one pack can Load the same asset at a time, so prefer edits when you can.
EditImage
Pastes your image over all or part of a game image: portraits, character sprites, furniture, crops, tilesheets. Use FromArea and ToArea to edit only one part.
EditData
Adds or changes entries in data assets such as dialogue, items, shops, events or recipes, without replacing the whole file.
EditMap
Changes a map or pastes part of one map into another, for example to add a path or a building area.
Include
Loads more patches from another JSON file, which keeps a large pack organized.

Every action can use conditions and tokens, for example a different portrait for each season or dialogue that only appears after you marry a character. Learn how on the Tokens & Animations page.

How to update Content Patcher and your mods

  1. Start the game through SMAPI. On launch it checks for updates and lists mods with a newer version.
  2. Download the new version. For Content Patcher, use the Download page.
  3. Delete the old folder from Mods and unzip the new one in its place. If you changed settings, keep a copy of the mod’s config.json and put it back afterwards.
  4. Launch through SMAPI again and check the console for red errors.

After a major Stardew Valley update, update SMAPI first, then Content Patcher, then your content packs.

How to remove a content pack

Because Content Patcher never overwrites game files, removing a pack is simple: close the game, delete the pack’s folder from Mods and start the game again. The original content comes back automatically.

Packs that only change images or dialogue can be removed at any time. Packs that add items, buildings or locations may leave objects behind in a save, so back up your save files before removing them mid-playthrough.

Troubleshooting

  • The game starts without mods: launch it through SMAPI, not the regular game shortcut.
  • Content Patcher doesn’t load: check that Mods/ContentPatcher/manifest.json exists and that SMAPI is up to date.
  • A content pack has no effect: read the SMAPI console for red error lines and install any requirements the pack lists.

More fixes, including “Content Patcher not working” and “can’t apply image patch”, are on the Troubleshooting page. Still stuck? See the FAQ or contact Support.