Upgrading Ghost


This article outlines all of the information you need to upgrade your version of Ghost and a changelog of all major version breaking changes.

Upgrade information

Select the correct upgrade guide below:

Follow the steps on screen to upgrade your version of Ghost. We always recommend running the latest version to unlock all of the latest features in Ghost and ensure your site is fully secure.

Major Version Changelog

This changelog is a list of backwards-incompatible updates in the API and in the Ghost theme layer.

Ghost 3.0

  • The Subscribers labs feature has been replaced with the Members labs feature.
  • The v0.1 API endpoints & Public API Beta have been removed. Ghost now has a set of fully supported Core APIs. See the switching notes below.
  • Themes using GhostHunter must upgrade to GhostHunter 0.6.0.
  • Themes using ghost.url.api() must upgrade to the Content API client library.
  • Themes may be missing CSS for editor cards added in 2.x. Use gscan to make sure your theme is fully 3.0 compatible.
  • New /v3/ (stable) and /canary/ (experimental) API versions have been added.
  • The /v2/ (maintenance) endpoints will not receive any further changes.
  • v3 Content API /posts/ & /pages/ don't return primary_tag or primary_author when ?include=tags,authors isn't specified (these were returned as null previously).
  • v3 Content API /posts/ & /pages/ no longer return page: true|false.
  • v3 Content + Admin API /settings/ no longer returns ghost_head or ghost_foot, use codeinjection_head and codeinjection_foot instead.
  • v3 Admin API  /subscribers/* endpoints are removed and replaced with /members/*.
  • v3 Content + Admin API consistently stores relative and serves absolute URLs for all images and links, including inside content & srcsets.

Switching from v0.1 API

  • The Core APIs are stable, with both read & write access fully supported.
  • v0.1 Public API (read only access) is replaced by the Content API.
  • v0.1 Private API (write access) is replaced by the Admin API.
  • v0.1 Public API client_id and client_secret are replaced with a single key, found by configuring a new Custom Integration in Ghost Admin»Integrations.
  • v0.1 Public API ghost-sdk.min.js and ghost.url.api() are replaced with the @tryghost/content-api client library.
  • v0.1 Private API client auth is replaced with JWT auth & user auth now uses a session cookie. The  @tryghost/admin-api client library supports easily creating content via JWT auth.
  • Scripts need updating to handle API changes, e.g. posts and pages being served on separate endpoints and users being called authors in the Content API.

Ghost 2.0

  • API: The /v2/ API replaces the deprecated /v0.1/ API. See the switching notes above.
  • Themes: The editor has gained many new features in 2.x, you may need to add CSS to your theme for certain cards to display correctly. See the latest advice on styling cards.
  • Themes: {{#get "users"}} should be replaced with {{#get "authors"}}
  • Themes: multiple authors are now supported, swap uses of author for either {{#primary_author}} or {{authors}}.
  • Themes: can now define which version of the API they want to use by adding "engines": {"ghost-api": "vX"}} to the package.json file.
  • Themes: there are many minor deprecations and warnings, e.g. @blog has been renamed to @site, use gscan to make sure your theme is fully 2.0 compatible.
  • v2 Content+Admin API has split /posts/ & /pages/ endpoints, instead of just /posts/.
  • v2 Content API has an /authors/ endpoint instead of /users/.
  • v2 Admin API /posts/ and /pages/ automatically include tags and authors without needing ?includes=.
  • v2 Content + Admin API attempts to always save relative & serve absolute urls for images and links, but this behaviour is inconsistent 🐛.

Ghost 1.0

  • This is a major upgrade, with breaking changes and no automatic migration path. All publications upgrading from Ghost LTS versions (0.x) must be upgraded to Ghost 1.0 before they can be successfully upgraded to Ghost 2.0 and beyond.
  • See announcement post and developer details for full information on what we changed in 1.0.
  • v0.1 Public API  /shared/ghost-url.min.js util has been moved and renamed to /public/ghost-sdk.min.js
  • Ghost 0.11.x LTS exports don’t include clients and trusted_domains so these aren’t imported to your new site - you'll need to update any scripts with a new client_id and client_secret from your 1.0 install.
  • Themes; Many image fields were renamed, use gscan to make sure your theme is 1.0 compatible.