Installation Guide
Follow these steps to install Content Patcher
and start using content packs.
SMAPI
- Install SMAPI first.
- Download Content Patcher from this site.
- Place it in your Mods folder.
- 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.
Content Patcher
- Open the Download page and click Download Now.
- Unzip the archive you downloaded.
- Move the ContentPatcher folder into Stardew Valley/Mods.
- Launch the game through SMAPI and check that Content Patcher appears in the console.
The path must be Mods/ContentPatcher/manifest.json — not a folder inside another folder.
Content Packs
- Pick a content pack made for Content Patcher (folder names often start with [CP]).
- Unzip it into your Mods folder, next to ContentPatcher.
- Launch the game through SMAPI — the pack loads automatically.
- To uninstall, simply delete the pack’s folder.
Each content pack lists its own requirements — install those too.
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:
- Update the game to the latest 1.6 version and start it once without mods.
- Install the latest Stardew Valley SMAPI release (the Stardew Modding API). Version 4.0 or later is required for 1.6.
- Open the Download page, get Content Patcher and unzip the archive.
- Move the ContentPatcher folder into Stardew Valley/Mods.
- Unzip each content pack into the same Mods folder (pack folders often start with [CP]).
- 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
{
"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
{
"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
FromAreaandToAreato 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
- Start the game through SMAPI. On launch it checks for updates and lists mods with a newer version.
- Download the new version. For Content Patcher, use the Download page.
- 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.
- 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.
