Ghost 2.0 was released in September 2018 and the second major upgrade since the platform launched. This update includes a new editor, a flexible configuration layer called dynamic routing, and lots of exciting new features.

There are minimal breaking changes for the Ghost 2.0 upgrade, which runs smoothly using ghost-cli.

This guide is useful for all self-hosted Ghost users. If you are using Ghost(Pro) then you are automatically upgraded to the latest version of Ghost.

Why upgrade to 2.0?

Using the latest version of Ghost is recommended to ensure that your site is secure and so that you have access to all of the latest features inside Ghost.

If you are still running a Ghost LTS version (0.x), upgrade to Ghost 1.0 before upgrading to 2.0 — follow the upgrading to Ghost 1.0 guide. Here’s the current version history and end of life support.


Prerequisites

It is only possible to upgrade to Ghost 2.0 from versions 1.0 or higher and the latest Ghost CLI version is required to complete the upgrade. Here's a breakdown of the migration steps:

  1. Prepare your theme
  2. Make a backup
  3. Install the latest Ghost CLI version
  4. Update Ghost

Prepare your theme

The new editor in Ghost 2.0 comes with powerful rich editing features that require additional CSS in your theme. There are minimal breaking changes to themes which will require some attention prior to upgrading to 2.0.

Check theme compatibility using gscan

The fastest way to check your theme compatibility is using the tool gscan. It allows you to upload a zip file of your current theme to check for errors, deprecations and other compatibility issues.

  1. Download your current active theme as a .zip from the design settings page in Ghost admin
  2. Upload this file on the gscan page
  3. Select 2.0.0 as the Ghost version to check your theme for this migration

The tool lists all errors and provide a full explanation and description of how to update your theme. All items listed as “must fix” are required to be updated within your theme for the 2.0.0 migration. Items listed as “consider fixing” are recommended to ensure future upgrades are smoother.

For a full overview of the required theme support for the latest version of the Ghost Editor, read the handlebars theme documentation.

The supported Ghost 2.0 migration also runs gscan in the background to check if your theme is compatible before allowing the upgrade. Ensure your theme is updated and uploaded to your site in Ghost admin before proceeding.

Backup your content

The recommended Ghost 2.0 upgrade using ghost-cli is designed to be pain free, but we always recommend making a backup of your content before any major upgrades, particularly if you are running any form of custom install. It takes less than two minutes to create a full backup of your site content, so make sure you follow this step.

JSON export

Retrieve an up-to-date JSON export from the Ghost admin in the labs section, which can be accessed at yourdomain.com/ghost/settings/labs/. This downloads a JSON export file that you can save in case of emergencies.

Content folder backup

All user-provided data such as images and themes exist in the /content/ folder.

We strongly recommend making a copy of these files. To do this run the following command on your sever:

cp -r content /tmp/content-backup

Install the latest Ghost CLI version

The Ghost 2.0 upgrade requires version 1.9.0 or higher of Ghost-CLI.

If you followed the supported install guide to production, the server setup has a single system-wide version of node.js. The install and update command for
ghost-cli can be used:

sudo npm i -g ghost-cli@latest

or if you used yarn:

sudo yarn global add ghost-cli@latest

Update Ghost

In your terminal cd into your publication’s directory and run the update command: ghost update. Ghost CLI checks that everything is ready for the upgrade and inform you if there are any extra steps required.

Once all checks have been passed the upgrade installs and you’ll be running Ghost 2.0.

Checking your theme ✅

The CLI will check your active theme for compatibility during the update process. Providing you followed the steps within this guide, you should see:

Checking theme compatibility for Ghost 2.0.0

✔ Your theme is compatible.

Visit the demo post at http://localhost:2370/p/a8501e8d-0d43-49ae-81b2-e5031c98d952/ to see how your theme looks like in Ghost 2.0
You can also check theme compatibility at https://gscan.ghost.org

? Are you sure you want to proceed with migrating to Ghost 2.0.0? (Y/n)

Once the migration is accepted, all existing posts have the <div class="kg-card-markdown"> wrapper element removed from the {{content}} output.

We highly recommend opening the demo post URL to perform a final check to make sure the post displays as expected before proceeding with the migration.


What to do when an upgrade fails

The most common reason for a failed upgrade is running out of memory. Ensure you have enough memory or configure swap memory on your server. If your install fails and you can't find a specific solution you run ghost uninstall and then try ghost install again.

Ghost accepts two optional flags for the ghost update command:

Force

If ghost update fails, the first thing to try is ghost update --force to retry the update.

Rollback

If your ghost install is in a broken state after updating, you can use
ghost update --rollback to get back to the previous stable version.

Once you've stabilised and resolved any underlying problems, go into /version and remove the broken version. Then run ghost update again. Use ghost --version to see what version is currently being used.

If you run into any other errors, use the search function on this site to find troubleshooting guides for common issues, or head to the community forum.


Summary

Following this guide you have upgraded to Ghost 2.0 using the Ghost CLI, after making any necessary changes to your theme. You now have access to all of the features inside Ghost 2.0.