Update a Ghost Theme Without Losing Your Settings

Quick answer: Ghost identifies an installed theme by the name of the zip file you uploaded, not by the name inside the theme. Upload the new version under the same file name and Ghost overwrites the files and keeps every setting you chose. Upload it under a new name, which is what a version number in the file name does, and you get a second theme with default settings. Edits you made to theme files are lost either way, so keep customisations in code injection or in a copy you control.

A new version of your theme has arrived. You have spent time on the settings, maybe changed a template or two, and the question is whether updating will undo that work. The answer depends on three things that live in three different places, and on one detail of how Ghost names a theme that almost nobody knows.

This guide explains the mechanism, shows what we found when we tested it on one of our own sites, and ends with a short routine that makes an update safe. It applies to any theme, on Ghost(Pro) or self-hosted.

Three things, three places

When you look at your site, three separate layers produce what you see, and an update touches only one of them.

The theme files. Templates, stylesheets and scripts inside the zip. Uploading a new version replaces them. Anything you changed in those files, through Ghost’s built-in code editor or by editing the zip, is overwritten.

The theme’s settings. The options a theme exposes under Settings → Design & branding → Customize, on the Theme tab: layouts, colours, toggles, text fields. These are not in the files. Ghost stores them in its database against the installed theme entry. Whether they survive an update depends entirely on whether the new upload lands on the same entry, which the next section explains.

Everything that is not the theme. Your brand colour, logo and icon, navigation, code injection, redirects and routes file, and every post and page. None of it belongs to the theme, and none of it is touched by a theme update. Code injection in particular survives everything, which is why it is the safest place for small customisations.

How Ghost decides which theme you are updating

Here is the detail that causes most lost settings. A Ghost theme has two names. One is inside it, in the package file, and it is what the theme calls itself. The other is the name of the zip file you upload. Ghost uses the second one to name the installed entry, and the entry is what settings attach to.

So if your theme’s file is mytheme.zip and you upload the new version as mytheme.zip, Ghost recognises the entry. It asks whether to overwrite it, replaces the files and leaves the settings alone. If you upload the new version as mytheme-v2.zip, Ghost sees a name it has never met and installs a second theme next to the first. The second one has the same name inside, the same look, and every setting at its default.

We tested this on one of our own sites, with a small throwaway theme that has two settings, a text field and a toggle:

Step 3 is the one that generates support tickets. The theme looked updated, the version number was right, and every setting was gone. Step 4 shows that nothing was actually lost: the values were still attached to the first entry.

Ghost’s admin shows both names. In the installed list, the name in bold is the one inside the theme, and the name in parentheses is the entry, which is the file name you uploaded. The active theme card shows the entry name first and the version from inside the theme in brackets. That is how you can end up with an entry called one version running the files of another.

For the technical reader: Ghost’s upload code takes the zip’s file name, strips the extension, sanitises it, and uses that as the theme’s folder on disk. Custom settings are stored per folder name. Only the code editor’s “save as new theme” action copies settings from one entry to another; a normal upload never does.

The safe update routine

1. Download the current theme first. Under Settings → Theme, open Change theme, switch to Installed, and use the menu next to your theme to download it. If the update goes wrong, uploading this file under the same name puts everything back.
2. Write down or screenshot your theme settings. Open Design & branding → Customize, then the Theme tab. This takes a minute and removes the only real risk.
3. Check the entry name. In the installed list, the name in parentheses is the file name Ghost expects.
4. Rename the new zip to match. Theme makers often ship versioned file names, ourselves included, because they make it easy to see which version you downloaded. Rename the file to the entry name before uploading, and Ghost will treat it as an update rather than a new theme.
5. Upload and confirm the overwrite. Ghost shows a dialog naming the entry it is about to replace. That dialog is the sign you got the name right. If you see no dialog and a new row appears in the installed list instead, the name did not match.

6. Look at the site, then at the settings. New features usually arrive as new settings, so a fresh option with a default value is expected. An old option with a default value is not, and step 2 lets you tell the difference.

If the settings are already gone

If you have already uploaded under a new name and the theme sits at its defaults, nothing has been deleted. In the installed list, activate the older entry: your values are there. Note them, activate the new entry, and enter them again. Then delete the older entry so the two do not confuse you next time, and from then on upload under the name of the entry you kept.

There is one case where a setting disappears for good. If a new version of the theme renames a setting internally, Ghost’s documentation says the old value is dropped and the setting starts again at its default. That is a decision the theme maker made, not something you did, and the release notes should say so.

If you edited the theme’s files

An overwrite replaces every file, so edits made in Ghost’s code editor, or in the zip before you uploaded it, do not survive. Ghost’s own help page says the same about updating a modified official theme: it is not recommended, because the update overwrites the changes.

The way out is to move customisations to places an update cannot reach. Styling changes go into Settings → Code injection, where a few lines of CSS override the theme’s own; our code injection guide covers what that box can and cannot do. Layout choices usually exist as theme settings already, and it is worth checking before editing a template. What remains, real template changes, is the part you have to carry forward yourself. Keep a note of every file you changed and what you changed, and apply the same edits to the new version before uploading it.

For the technical reader, the durable way to do that is a small repository. Unzip the theme, commit it, and commit your changes on top. When a new version arrives, commit that version and merge your changes over it. Zip the result and upload it under the installed entry’s name. This is the workflow theme developers use, and it turns an update from an afternoon of re-doing edits into a few minutes of resolving differences.

If you have changed a theme so much that merging a new version is more work than the update is worth, you have a theme of your own now. Treat it as one, keep it under the name you gave it, and take from new releases only the changes you want.

Official themes and the Update button

Ghost’s own themes are a special case. Under Change theme, select the official theme you use and Ghost shows an Update button, which fetches the latest version for you. The same rule applies: if you modified the theme, the update overwrites your modifications. The default theme, Source, updates itself along with Ghost as long as you have not changed it.

Where this leaves you

You know which of the three layers an update touches, why the file name decides whether your settings survive, and how to check the entry name before uploading. Our own theme documentation carries the update steps for each theme, and from this month on it says to rename the download to match the installed entry. If the customisation you are protecting is a stylesheet tweak, the code injection guide is the next thing to read. If it is a whole layout, the theme’s own settings are worth a second look before any file is edited.