How to Upgrade Ghost

Self-Hosted / How to Upgrade Ghost

Note: just looking for the commands to run? Jump to the command guide at the end of this post.

Upgrading Ghost is still a very manual process at the moment. We realise that this is isn't ideal, however this guide should help you get updated to the latest version of Ghost smoothly.

Preparation

Before you start updating, there are a few highly recommended preparation steps that should help you get the best & quickest results:

1. Make a backup

We can't stress this enough - even if it all goes horribly wrong, recovering is quick and easy if you're properly backed up. Use the export tool on the labs page to create a .json file and make copy of the content folder in the root of your Ghost install - this contains your images and themes. Read our guide on importing & exporting for detailed instructions.

2. Check your restart command

How you restart Ghost is different based on how you setup Ghost in the first place. The most common restart command is service ghost restart, but if you're using forever it'll be something like forever restart index.js or if you're using pm2 then it's pm2 restart ghost. Make sure you have this, as well as your start and stop command to hand before you start upgrading.

Ordinarily, restarting Ghost is the last step of upgrading, but at that point it can be hard to debug whether there is something wrong with the upgrade or with the restart. Therefore, if you're unsure about restarting, make sure to test your restart command before you start upgrading. If you've made any configuration changes, or not restarted Ghost before, now's the time to check it works!

3. Consider the version jump

The changes between the version numbers in Ghost have significance. As we are still pre 1.0, semantic versioning doesn't fully apply, but we try to make sure that patch version upgrades; e.g. 0.6.4 to 0.6.5 are safe, whereas bigger changes are indicated with a minor version bump; e.g. 0.6.4 to 0.7.0. If you've fallen really far behind, you might not be able to upgrade direct to the latest version.

For blogs on 0.7.1 or greater, you should be able to upgrade straight to 0.11.1, but note it can take some time if you have a lot of data.

For blogs on version 0.5.0 or greater you should be able to upgrade to any 0.7.x version.

For blogs on version 0.4.2 (2 years old!) you must upgrade to Version 0.7.1 (0.7.0 had a couple of upgrade bugs which are ironed out in 0.7.1), before upgrading to any later 0.7.x version.

For blogs on anything before 0.4.2 you must do incremental upgrades until you get to 0.4.2.

Upgrading

Now you've prepared, you're ready to perform the upgrade. The following steps explain what needs to happen in detail. If you want a quick-list of commands, check the command guide at the end of the article.

1. Fetching the latest Ghost version

Now you're ready to do the upgrade, the first step is to grab the latest copy of Ghost. You can get this from the Ghost.org download page, from the GitHub release page or by using either wget or curl -LOk to grab the latest version from the special 'latest' URL https://ghost.org/zip/ghost-latest.zip, which always gives you the current version.

curl -LOk https://ghost.org/zip/ghost-latest.zip - example code used to download latest version of ghost

2. Unzip / Extract

Next, you need to extract the zip file you just downloaded to a temporary location. We do not recommend unzipping over the top of your install for two reasons: first it leaves behind any old files which don't exist in the new version, and second it can result in overwriting your content directory. Most systems have an archive utility or an unzip command which can be used to do this, E.g. unzip ghost-0.7.0.zip -d ghost-0.7.0.

3. Delete the old files

Navigate to your Ghost installation folder and delete the core directory. This contains most of the files which make up the Ghost software. Do not delete the content directory.

You can also delete the index.js file, and all the files ending with .md and .json. Do not delete your config.js file. You may prefer to leave these files, and just copy the new versions over the top. The important thing is to delete the whole of the core directory.

4. Copy over the new files

Copy the core directory from your newly downloaded latest version of Ghost. Also be sure to copy & replace index.js, package.json and npm-shrinkwrap.json - getting the latest copies of these 3 files is critical to the upgrade completing successfully.

You may also want to copy over the latest versions of the .md files like README.md or PRIVACY.md so you have them to hand as these contain useful info.

If you're using Casper - the default theme - without modifications then you'll also want to copy the content/themes/casper folder from the latest version into place in your install directory.

cp -R path-to-unzipped-ghost-folder/content/themes/casper path-to-ghost-install/content/themes

5. Check your permissions

After coping the files over, you need to check they have the correct permissions. They should be owned by the user which runs Ghost, which may be different to the user you are logged in with. E.g. if you have a ghost user & group for running Ghost (highly recommended), you'd need to run chown -R ghost:ghost core to update the permissions of the core directory.

6. Update your dependencies

On the command line, whilst inside your Ghost installation directory (if you type ls in this directory you should see both the core and content directories), run the command npm install --production and wait for this to complete.

This step needs to complete successfully without errors (warnings are OK) for the next step to work. If anything goes wrong there will be details in a file called npm-debug.log. The first thing to try if this step fails is always to remove the node_modules folder, run npm cache clean and try again.

7. Restart Ghost

This is the moment of truth! For most upgrades, just restarting using your restart command at this point should be fine.

Sometimes Ghost will perform update tasks on the first start after an upgrade. If you aren't confident you know where to find your logs, it may help to run the first start on the command line. To do this, run your stop command, and then run npm start --production. Ghost will output information about what it is doing, and tell you when it is done.

Once this is complete, press ctrl+c to exit and use your normal start command to get Ghost running normally again.

Troubleshooting

If Ghost comes back from an upgrade without your data or theme, chances are you restarted in a different mode: e.g. development instead of production. Make sure you use the correct restart command, and that your environment is configured to run Ghost in the same mode each time.

The most common issue with upgrading is getting npm install --production to complete.

If you have trouble with this step, the first thing to try is to delete your node_modules folder, run npm cache clean, and try again. If this also fails, upgrading npm may help. Also check you have the latest version of npm-shrinkwrap.json.

Another common problem with upgrades is permissions of the copied files being incorrect. E.g. if you logged in as root to perform the update and your Ghost install runs as a ghost user, you'll need to make sure all the files are owned by the ghost user.

For details on specific errors, see our troubleshooting guide

Finally, if you get weird, code-related errors such as ERROR: Object function (){ parent.apply(this, arguments); } has no method 'findPage', it is very likely that you missed deleting the core folder before copying over the new version. Please repeat the upgrade, following the steps in this guide closely.

Checking your restart command is correct and then repeating all of the upgrade steps one-by-one is always the first thing to try after a failed upgrade.

Command Guide

The following commands are examples of how to perform each step, you will need to update the command with the correct paths and details for your own setup.

Version Warning:

We recommend upgrading from any version > 0.5 to 0.7.1 first and then to 0.11.1.


  1. Get the latest version:
    curl -LOk https://ghost.org/zip/ghost-latest.zip OR a specific version curl -LOk https://ghost.org/zip/ghost-<version>.zip

  2. Unzip to a temporary location:
    unzip ghost-latest.zip -d ghost-temp

  3. Change directory into your current ghost install:
    cd path-to-ghost-install, E.g. cd /var/www/ghost

  4. Remove the core directory completely:
    rm -rf core

  5. Change back to your download of Ghost latest:
    cd path-to-ghost-temp E.g. cd ~/Downloads/ghost-temp

  6. Copy the new core directory to your Ghost install:
    cp -R core path-to-ghost-install

  7. Copy the other key files to your Ghost install directory:
    cp index.js *.json path-to-ghost-install

  8. (optional) Update Casper by copying the casper folder:
    cp -R content/themes/casper path-to-ghost-install/content/themes

  9. Change back to your ghost install directory:
    cd path-to-ghost-install

  10. (optional) Update permissions:
    E.g. chown -R ghost:ghost *

  11. Upgrade dependencies:
    npm install --production

  12. Restart Ghost
    E.g. service ghost restart or forever restart index.js or pm2 restart ghost or npm start --production

Note:

Not working? Please see the troubleshooting guide above.

How to Upgrade Ghost

Self-Hosted / How to Upgrade Ghost