How to Upgrade Ghost Installation

This guide walks you through upgrading a self-hosted Ghost installation on a VPS or server. Whether you're running on Ubuntu, Debian, or another Linux distribution, these steps will help you safely update Ghost to the latest version while avoiding common pitfalls.

Updated July 2026: recent Ghost-CLI versions now use pnpm to perform updates (see Step 6), and there's an important warning about not blindly updating npm.

Prerequisites

Before you begin, ensure you have:

• SSH access to your server
• sudo privileges for your user account
• At least 1GB of RAM available (the most common cause of update failures is running out of memory)
• A recent backup of your Ghost installation

Step 1: Check Your Current Setup

First, SSH into your server and check your current versions:

# Check Ghost version and installation location
ghost ls

# Check current Node.js version
node -v

# Check Ghost-CLI version
ghost -v

# Check npm version
npm -v

Important: Take note of these versions. You'll need them if something goes wrong.

Step 2: Create a Backup

Never skip this step. Create a full backup before any upgrade:

cd /var/www/ghost  # or your Ghost installation directory
ghost backup

This creates a zip file containing:

• Content (JSON export)
• Member data (CSV)
• Themes
• Media files
• Configuration files

Pro tip: Download the backup to your local machine:

# From your local machine
scp user@your-server-ip:/var/www/ghost/backup-*.zip ~/Desktop/

Step 3: Check Node.js Version Requirements

Ghost has strict Node.js version requirements:

Check the official Node.js requirements for the most current information.

Step 4: Update Node.js (If Required)

If your Node.js version is outdated, update it first:

# Check current version
node -v

# Install Node.js 22.x (for Ghost 6.x)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify new version
node -v

Alternative using nvm (Node Version Manager):

# Install specific version
nvm install 22

# Use it
nvm use 22

# Set as default
nvm alias default 22

Important — if you use nvm and run Ghost via systemd: the Ghost service unit hardcodes the full path to the Node binary (for example /home/user/.nvm/versions/node/v22.21.1/bin/node). Upgrading Node with nvm does not update that path, so Ghost keeps running the old Node until you fix the unit. See "Ghost is running with the old Node version" in Troubleshooting.

Step 5: Update Ghost-CLI

Always update Ghost-CLI before updating Ghost itself:

npm install -g ghost-cli@latest

# Verify version (should be 1.28.2 or higher for Ghost 6.x)
ghost -v

Note: if Node is installed via nvm (in your user's home), do not prefix this with sudo — global installs go into your nvm directory, and using sudo can create permission problems.

Step 6: Install pnpm (Required for Ghost 6.x updates)

Recent versions of Ghost-CLI use pnpm — not npm — to download and install Ghost during an update. If pnpm is missing, ghost update fails immediately with:

A ProcessError occurred.
Message: spawn pnpm ENOENT

Install pnpm with corepack, which ships with Node.js (so it works even if npm is misbehaving):

corepack enable pnpm
pnpm --version   # confirm it prints a version

⚠️ Do NOT run npm install -g npm@latest. A newer npm major (such as npm 12) may be built for a newer Node.js than you're running, and updating into it can break npm itself — you'll see errors like Cannot find module 'promise-retry', and a broken npm can't reinstall itself. If you genuinely need npm, pin it to the major that ships with your Node version (Node 22 → npm install -g npm@10). With pnpm handling updates, you rarely need npm at all.

Step 7: Switch to the Correct User

Ghost must be managed by the user who originally installed it (the owner of the Ghost directory), in an interactive terminal:

# Switch to the install user (e.g. 'ghost' or your username)
sudo -i -u yourusername

Step 8: Navigate to Ghost Directory

cd /var/www/ghost  # Default location, yours may differ

Step 9: Update to Latest Minor Version First

If you're upgrading across major versions (e.g., 4.x to 5.x to 6.x), you must first update to the latest minor version of your current major release:

# If on Ghost 4.x, update to latest 4.x first
ghost update v4

# If on Ghost 5.x, update to latest 5.x first
ghost update v5

Step 10: Perform the Update

Now run the actual update:

ghost update
ghost doctor   # confirm all checks pass afterward

Ghost-CLI will:

• Download the latest version (using pnpm)
• Check compatibility
• Run database migrations
• Restart Ghost

Troubleshooting Common Issues

Error: spawn pnpm ENOENT

Ghost-CLI can't find pnpm (required by recent versions). Install it, then re-run the update:

corepack enable pnpm
ghost update

Error: Cannot find module 'promise-retry' (broken npm)

This happens after installing an incompatible npm major (e.g. npm install -g npm@latest pulling npm 12 onto Node 22). A broken npm can't reinstall itself, so bootstrap a fresh one and pin it to your Node's major:

nvm use 22
curl -qL https://www.npmjs.com/install.sh | sh   # installs npm without needing the broken npm
npm install -g npm@10                            # pin to the Node 22-compatible major
npm --version

Error: Ghost is running with the old Node version

After upgrading Node with nvm, ghost doctor may warn: "Ghost is running with node vX.OLD" while your current node is newer. Ghost's systemd unit still points at the old Node path, and ghost setup systemd will skip an existing unit instead of regenerating it. Fix the unit directly:

# find the unit and confirm the new node+ghost binaries exist:
systemctl show ghost_<yourdir> -p FragmentPath
ls /home/user/.nvm/versions/node/vNEW/bin/{node,ghost}

# repoint the service (swap old version string -> new), reload, restart:
sudo sed -i 's|vOLD|vNEW|g' /usr/lib/systemd/system/ghost_<yourdir>.service
sudo systemctl daemon-reload
sudo systemctl restart ghost_<yourdir>
ghost doctor   # the node-version warning should be gone

Error: Node Version Mismatch

Ghost v6.x.x is not compatible with the current Node version.
Your node version is X.X.X, but Ghost vX.X.X requires ^22.0.0

Solution: Update Node.js as shown in Step 4.

Error: Ghost-CLI Version Too Old

Ghost v6.x.x is not compatible with this version of the CLI.

Solution: Update Ghost-CLI:

npm install -g ghost-cli@latest

Error: Update Failed (Memory Issues)

FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory

Solution: Increase Node.js memory limit:

NODE_OPTIONS="--max-old-space-size=1024" ghost update

Or temporarily add swap space:

sudo fallocate -l 1G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
# Run update, then remove swap if desired

Error: MySQL Connection Issues with Node 18+

Node.js 18+ prefers IPv6, which can cause MySQL connection failures.

Solution: Edit your Ghost config to use 127.0.0.1 instead of localhost:

ghost config set database.connection.host 127.0.0.1

Error: Binary Dependencies Need Recompilation

After updating Node.js, Ghost's binary dependencies may need recompilation.

Solution: Force reinstall:

ghost update --force

Error: Permission Denied

The path /home/user/ is not readable by other users

Solution: Fix permissions:

sudo chown -R ghost:ghost /var/www/ghost
sudo chmod 775 /var/www/ghost

Site Shows 503 Error After Update

Solution: Check logs and try restarting:

# Check what's happening
ghost log

# Try restarting
ghost restart

# If that fails, run directly to see errors
ghost run

Rolling Back

If the update fails catastrophically, you can roll back:

ghost update --rollback

Or restore from your backup manually.

Post-Update Verification

After a successful update, verify everything works:

# Check Ghost is running
ghost status

# Check the version
ghost version

# View recent logs
ghost log

# Visit your site in a browser
# Check the admin panel at https://yoursite.com/ghost/

Best Practices

• Always backup first — this cannot be stressed enough
• Update during low-traffic hours — minimize impact on readers
• Test in staging first — if possible, test updates on a staging server
• Read the changelog — check Ghost's changelog for breaking changes
• Keep Ghost-CLI updated — many issues stem from outdated CLI versions
• Pin npm to your Node major — never npm install -g npm@latest
• Monitor after updates — watch logs for the first few hours after updating

Quick Reference: Common Commands

# Check status
ghost ls
ghost status

# Start/Stop/Restart
ghost start
ghost stop
ghost restart

# View logs
ghost log
ghost log -f  # Follow logs in real-time

# Backup
ghost backup

# Install pnpm (required for updates)
corepack enable pnpm

# Update
ghost update
ghost update --force     # Force reinstall
ghost update --rollback  # Undo last update

# Diagnostics
ghost doctor
ghost doctor startup

# Configuration
ghost config             # View all config
ghost config url         # View specific setting
ghost config set url https://example.com  # Change setting

References

• Ghost Official Update Guide
• Ghost Node.js Version Requirements
• Ghost CLI Documentation
• Ghost Changelog
• NodeSource Node.js Distributions