Developer docs
Docs / Update /

How to update Ghost

Learn how to upgrade the Ghost publishing platform with just a couple of steps.

If you’re upgrading to a new major version you need to take care of any breaking changes.

First, make a full backup

Whenever doing a manual update it’s a good idea to take a full backup of your site first. If anything goes wrong, you’ll still have all your data.

Update to the latest minor version

Before updating to a new major version (e.g. updating from Ghost 3.x to Ghost 4.x), you must update your site to the latest minor version.

For example if you’re on 2.33.0, you need to upgrade to 2.38.3 (the latest 2.x version) first, and then to 4.x. You do not need to upgrade through every major version.

If you installed Ghost using Ghost-CLI, the ghost update command will inform you of the commands to run to perform the necessary intermediate updates.

Export your content and members

Export

Start by exporting a JSON file of all your posts from the labs area of Ghost Admin.

Then, make a copy of your entire /content directory as a backup for themes and images:

# Duplicate the content directory
cp -r content /backup/content

Your members can be exported to a CSV file from the Members page of Ghost Admin.

Your theme may need to be updated

Depending on your current version of Ghost, you might need to make some changes to your theme.

To see what changes are need to be made, download a copy of your theme zip file, and upload it to our GScan automatic theme compatibility testing tool.

GScan will provide a report on any new features in the Ghost theme API which are not being used, or any old ones you might be using which have been deprecated - so you can get everything fixed up.

Gscan

Run the Ghost update command

When you’re ready, make sure you’re in your site’s root directory and then run the Ghost update command using Ghost-CLI.

# Ensure your CLI is up to date
sudo npm install -g ghost-cli@latest
# Run the update
ghost update

Troubleshooting any problems

The most common reason for an update failure is running out of memory, so make sure you have enough RAM or swap configured in advance.

Force update

If an update fails you can start by forcing a retry to attempt the upgrade a second time.

# Force retry
ghost update --force

Rollback

If something goes wrong, you can always revert to the previous stable version of Ghost.

# Revert
ghost update --rollback

If you’re still having trouble, start by searching the Ghost forum to see if your issue has come up before.

Create a brand new Ghost install

If there is no direct upgrade path to the latest version of Ghost, you’ll need to follow the setup guide and create a brand new install to migrate to.

Major versions of Ghost break compatibility to allow the platform to evolve. Creating a new install means you’ll have the latest version of the app while still being able to import your old content.

On Ghost(Pro) this takes a few clicks, or if you’re self-hosting you can follow our in-depth guides.

New publication

# Install the latest version
ghost install

Migrate your content from old to new

Once the new install is set up, the only thing left to do is to import all of the content which was backed up at the start of this process.

Import JSON

To begin the migration, head to the Labs section of Ghost Admin and import the ghost.json backup which you exported earlier. The importer will let you know if there are any issues.

Upload theme

Next, upload your updated theme to the Design section of Ghost Admin to get your site looking the same way it did before. Again, the theme uploader will tell you if there are any issues.

Copy over images

All images from /content/images/ should be copied over to your new install.

# Verify content dir permissions
sudo chown -R ghost:ghost content

Import members

If you have paid members, you’ll need to reconnect to the same Stripe account your previous Ghost instance was connected to. You can then import your members from the CSV you exported earlier.

Password tokens are not migrated, so all users will need to go through the password reset flow to unlock their accounts. If you have any trouble, start by searching the docs and the forum for help!