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
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.
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.
# 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!