Before updating to a new major version, you must update your site to the latest minor version, e.g if you are on 4.23.0 you need to be on 4.48.9 before updating to v6. You also need to make sure that your setup meets all the latest requirements. This guide will take you through everything step-by-step. Updates are recommended for sites that are:
  • Running Ghost version 3.0.0 or higher and are using MySQL in production
  • Development sites using any database
The web analytics feature is not compatible with Ghost-CLI. There is a docker-based hosting method currently in preview, which includes a migration tool for Ghost CLI sites: check it out.

​
Switch user

Switch to the user you used to setup your Ghost install for running Ghost commands: 
sudo -i -u <user>

​
Update Node

Run node -v to check your node version. If less than 22, update node: 
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

sudo apt-get install -y nodejs

​
Update Ghost CLI

Ghost-CLI is an npm module that can be updated using npm: 
sudo npm install -g ghost-cli@latest
You can run ghost -v to see what version of Ghost-CLI you have. For Ghost 6.0, it’s best to have v1.28.2 or higher.

​
Update to the latest minor version

Before updating to a new major version, you must update your site to the latest minor version and not be more than 2 majors behind. First, perform a backup of your site: ghost backup Then, update to the latest minor version:
  • On Ghost 3.0 run ghost update v3 and then ghost update v4
  • On Ghost 4.0 run ghost update v4
  • On Ghost 5.0 run ghost update v5
If Ghost is not already running, run ghost start, then login to Ghost Admin and check this update has worked before continuing.

​
Make a full backup

When performing manual updates it’s a good idea to make frequent backups, so if anything goes wrong, you’ll still have all your data. Once you’re running the latest minor version, make a full backup using the following command to generate a download of your site’s data: 
ghost backup
This creates a backup zip file of everything you need, including:
  • Your content in JSON format
  • A full member CSV export
  • All themes that have been installed including your current active theme
  • Images, files, and media (video and audio)
  • A copy of routes.yaml and redirects.yaml or redirects.json
Read more about how to manually download your site data.

​
Check MySQL version

MySQL 8 is the only supported database in production. Use the following commands to check your database version: 
ghost config database.client
This should output sqlite3 or mysql. If it says mysql, run mysql --version to find the details of your mysql install. If you’re already running MySQL 8, proceed to the next steps. Otherwise, read more about how to update or migrate your database if you’re using any other version.

​
Review breaking changes

Major versions often contain breaking changes that impact themes and the API. Ghost CLI will output a report with any theme incompatibility errors and recommendations, or you can upload your theme directly to the GScan theme testing tool. If you make use of the API e.g. in themes, custom integrations or on a headless site, you should carefully review changes to the API before updating to ensure you don’t need to update your custom tooling first. For example in Ghost 6.0 we’ve removed support for ?limit=all and many integrations may need to add pagination in order to handle this.

​
Get ActivityPub ready

If you’d like to use the social web features, you can use the Ghost(Pro) hosted ActivityPub service. This is done by adding two new location blocks to your nginx.conf file as shown here. The file can be found in: 
path/to/ghost/install/system/files/[your-domain].conf
The two blocks to add are (exactly): 
 location ~ /.ghost/activitypub/* {
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header Host $http_host;
    add_header X-Content-Type-Options $header_content_type_options;
    proxy_ssl_server_name on;
    proxy_pass https://ap.ghost.org;
}

location ~ /.well-known/(webfinger|nodeinfo) {
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header Host $http_host;
    add_header X-Content-Type-Options $header_content_type_options;
    proxy_ssl_server_name on;
    proxy_pass https://ap.ghost.org;
}
They should be added just before the standard location block. Then reload nginx with your new config 
sudo nginx -s reload
If you want to fully self-host the ActivityPub service, or self-host the web analytics features, you’ll need to try to try out the docker compose preview.

​
Update to the latest major version

Finally, you can now run the update command again to upgrade to the latest major version: 
ghost update

​
Troubleshooting

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.

​
Find your Ghost folder

Run the ghost ls command anywhere on your server to find the details of your Ghost install.

​
Download your backup

If you need to move your backup between machines, run the scp command on the machine you want to move the file to: 
scp user@123.456.789.123:/var/www/ghost/backup-from[...].zip ~/Desktop

​
Force update

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

​
Rollback

If something goes wrong, you can always revert to the previous stable version of Ghost. 
ghost update --rollback
If you’re still having trouble, start by searching the**Ghost forum**to see if your issue has come up before.

​
Downgrade Node

If you need to downgrade Node, these are the steps: 
sudo apt-get remove -y nodejs
curl -sL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs