How to keep custom design settings when updating your Ghost theme

When you're working with a Ghost theme, it's natural to make tweaks over time — maybe a small layout adjustment, a color update, or a new setting added to package.json. But if you've ever uploaded a modified version of your theme and suddenly found all your design settings reset to their defaults, you're not alone.

This usually happens when you upload a theme that has been renamed or repackaged. Ghost treats each uniquely named theme as a separate entity, which means it loads the default values from the new theme's package.json instead of preserving your previously customized settings.

In this guide, we'll walk through why this happens, and more importantly, how to safely update your theme without losing your custom design settings.

Why settings get reset

Ghost themes can define custom design settings using the config key in package.json. These settings appear in Ghost Admin under Settings → Design, where users can easily customize things like colors, fonts, layout options, and more — all without editing code. Learn more about custom design settings.

Ghost ties these settings to the theme name, so when you upload a new theme, or even the same theme with a different name (even a small change in the zip filename or name field inside package.json), Ghost treats it as a completely new theme.

Ghost will prompt you to "Activate" the new theme rather than showing an "Overwrite" prompt. This activation prompt is a clear indicator that Ghost sees this as an entirely new theme, not an update to your existing one.

As a result, it loads the default values defined in the new theme's package.json, and your previous customizations are lost.

This often happens when:

• You rename the zip file before uploading
• You change the name field in package.json
• You upload the same theme under a different name for testing

Understanding this behavior is key to preserving your design settings during theme updates.

The 'correct' way to update a theme

To avoid losing your custom design settings, you have two options:

1. Use the same zip filename when manually uploading a theme
2. Use a GitHub action to deploy your theme

Manually upload a theme with the same name

If you are manually uploading a theme, the key is to keep the theme name the same when updating. The safest and most straightforward method is to upload a .zip file that uses the same name as your current theme — both in the filename and inside the package.json file.

Ghost will recognize it as an update to the existing theme, you get a prompt to confirm the update and if you confirm, it will retain all your settings.

Steps:

1. Make your changes to the theme files locally.
2. Ensure the name field in package.json stays exactly the same.
3. Zip the theme folder with the same name as the one currently installed.
4. In Ghost Admin, go to Settings → Design → Change theme → Upload theme.
5. When prompted to replace the existing theme, confirm it.

Ghost will overwrite the theme without touching your saved design settings.

Use GitHub deploy workflow

Instead of manually uploading a theme after making changes, you can use a GitHub action to deploy your theme.

As long as the theme name in package.json remains unchanged, Ghost will deploy updates to the existing theme without resetting any settings.

This approach is ideal as you don't have to worry about zip files, manual uploads, just make changes via Git or GitHub and the changes are automatically deployed.

Learn more about how to set up a GitHub action to deploy your theme in the Ghost GitHub Action guide.

If your settings were already reset

If you've already uploaded a renamed theme, your settings aren't lost (unless you delete the previous active theme).

Here's what you can do:

• Re-activate your previous theme
• Upload the the changed theme again but using the same name for the zip file
• If you can't do the above, you'll have to manually reapply your previous settings

Keeping your Ghost theme's custom design settings intact during updates comes down to understanding how Ghost handles theme identity. By maintaining consistent theme names in both your zip files and package.json, or by utilizing GitHub deploy workflows, you can safely update your theme without losing your design settings.