Install (local / dev)

Installing locally for testing, theme development, etc

This installs a site that will run in development mode (with less internal caching) and using sqlite3.

Local installs are not suitable for production

Using ghost install local to create a minimal install and then hacking it for production use is an anti-pattern.

ghost install is flexible. If you want to skip parts of the process, this can be done via the prompts or via flags - please read though our install reference for more information. If you modify a local install for production, you should not expect that ghost update will work.

Any questions, come see us @ https://slack.ghost.org.

If you want to customise Ghost core, or perhaps contribute some code back to the upstream repository, you'll need to follow the working with ghost guide to get a git clone working.

However, if you'd like to get Ghost installed on your local machine to try Ghost out, or develop a theme (or an adapter, or perhaps one day even an app) then this is the guide for you!


The TL;DR version of local installs, is you want to make use of Ghost CLI's super handy command:

ghost install local

This command is intended to work seamlessly on Mac and Windows, and should probably also work well on linux & unix machines, however the latter may need a few tweaks.

Problems or ideas?

If you run into problems, or have an idea for how we can make Ghost CLI even better, please raise an issue on the Ghost CLI repository. Provide as much info as you can, and we love PRs ❤️

Check your Node version

Ghost works with all LTS versions of Node.js, see our Supported Node Versions guide for more information.

Using nvm?!

If you are using nvm on your local machine, you need to be very careful about using the same environment when you install Ghost CLI and when you run ghost commands. This is particularly important when trying to use Ghost with sqlite3.

Please read our using nvm guide for more information about making sure nvm is configured correctly before you start!

Install Ghost-CLI

When running on your local machine, there is no requirement to use a non-root user, in fact it's probably more desirable to not need sudo everywhere. The command:

npm install -g ghost-cli

Should install Ghost CLI for you. Even better, use the short form of install, and force the @latest version:

npm i -g ghost-cli@latest

This version of the command will ensure Ghost CLI is installed at the latest version. This is also the same command you need to update Ghost CLI, so use this and you'll only ever need to remember one command.

If you're using yarn, you'll want to adjust this slightly to:

yarn global add ghost-cli@latest

Ghost CLI requires no configuration or setup. Once you've got it installed as a global module, you'll have the full suite of ghost commands ready at your disposal.

Install Ghost

The only prerequisite to a local install, is that you create a clean empty directory ready for Ghost to be installed into. Once you've got your directory, cd into it and then run one command:

ghost install local

This command won't prompt you for any information, but it may take a few minutes. Maybe hit run and go make that coffee you've been wanting for the last 30minutes?

Ghost CLI will output lots of information about what it's doing, so that hopefully it's clear what's going on in the background. To explain a bit, here are the key bits of info about ghost install local:

  • It will setup your blog in development mode. This essentially means there is less caching than in production mode & logs only go to stdout, not to a file. Development mode is mostly useful for theme development.
  • It will use SQLite3 as the database. We do this because, if everything goes OK, it requires no input from you. It's great for developing on.
  • No additional setup steps will be run - meaning there's no attempt to configure nginx, or systemd or setup ssl etc.
  • Ghost will be run in a separate process and will stay running until you stop it (or restart your machine). Use ghost stop to stop Ghost, ghost log to view the logs and ghost ls (from anywhere) if you need a list of all the Ghost blogs you have running.

Developing themes

When using Ghost CLI, your custom themes need to live in the top-level /content/themes/ directory (e.g. not inside of the current or versions folders).

Live reloading

If you're developing a theme, it's useful to be able to restart Ghost if there are changes that it won't pick up automatically. This can be accomplished with a local install, by using nodemon.

First, make sure Ghost is stopped. Inside your local install directory, run:

ghost stop

Second, install nodemon globally:

npm install -g nodemon@latest

Next, make sure you've got a theme folder ready in content/themes, with the basics of your new theme in place.

If you want to get started with Casper, note that Casper's CSS files are compiled which means running some additional tools to process the "src" CSS and transform it to be fully browser compatible. Casper's readme has info on how to get started.

If you base your theme on Casper, don't forget to update the name in package.json.

If you make an empty folder, you'll need to create a post.hbs, and index.hbs and a valid package.json in that folder before starting Ghost, as those are the minimum requirements for a valid theme - visit the theme docs for details.

Now you are ready to start Ghost with nodemon:

nodemon current/index.js --watch content/themes/[your-theme-name] --ext hbs,js,css

This will start Ghost, watching all hbs, js and css files inside of the [your-theme-name] folder, so whenever you add new templates or make changes, Ghost will restart.

Validating with GScan

Whenever a theme is uploaded or activated in Ghost, it is validated with the GScan tool. You can run these checks yourself by globally installing the gscan npm package:

npm install -g gscan

Once this is installed you can run gscan <file path> anywhere to run the checks against a folder on your computer, E.g.

gscan /path/to/ghost/content/themes/casper

You can also run it on a zip file, by passing the -z flag

gscan -z /path/to/downloads/theme.zip

Install (local / dev)

Installing locally for testing, theme development, etc