/ghost-purge-images

CLI tool to display & purge the uploaded images, video and audio files that currently are not used in any post, page or meta data

Primary LanguageJavaScriptMIT LicenseMIT

ghost-purge-images

Display or clean unused uploaded files: images, documents, audio, video & thumbnail files of your Ghost blog

🎁 Versions compatibility

Which Ghost version are you running?

Ghost version ghost-purge-images version How to install
3, 4, 5 latest npm install -g ghost-purge-images
>= 2.16 2.1.1 npm install -g ghost-purge-images@2.1.1
<= 2.15.x 2.0.3 npm install -g ghost-purge-images@2.0.3
0.7.2 - 1.x 1.0.0 npm install -g ghost-purge-images@1.0.0

✨ Update to the last version

In your blog server, login via ssh and run:

npm install -g ghost-purge-images

💡 This command will install or update ghost-purge-images globally in your server, it doesn't matter in which folder you run it

🤓 Observations

  • Due Content & Admin API, some images associated to the next resouces will be removed:

    • Authors with zero published posts

    • Tags that are not associated with a post

    • Drafts (both posts/pages) will be removed too if you are not running Ghost v2.16 or newer

      💡 Why? Drafts are only available in Ghost Admin API included in Ghost 2.16

  • Backup your content folder first!

🔑 Keys

This tool use:

Get the keys following this steps:

  • On your Ghost admin, click on Integrations at the left menu
  • Click on Add custom integration and set any name
  • Copy the Content API & Admin API Keys to use them

💡 Need help? Check this step-by-step guide to create them

🚀 Execute

Login into your server via ssh:

  • Where you have installed Ghost, usually:

cd /var/www/ghost

  • Run a command, for example:

ghost-purge-images display --content-key=YOUR_CONTENT_KEY --admin-key=YOUR_ADMIN_KEY

⚡️ Commands

display

Print the list of all uploaded images that currently are not being used in any post, page or metadata

  • Example: ghost-purge-images display --content-key=YOUR_CONTENT_KEY --admin-key=YOUR_ADMIN_KEY

ghost-purge-images display screenshot

purge

Delete all the unused files.

⚠️ WARNING: Take a backup before run this

  • Example: ghost-purge-images purge --content-key=YOUR_CONTENT_KEY --admin-key=YOUR_ADMIN_KEY

ghost-purge-images purge screenshot

🧩 Optional Params

  • url

💡 By default, the URL in config.production.json will be used. This may be useful for Docker or custom configurations

Example: ... --url=https://yourblog.com/

  • images-path

💡 The default images path is content/images

You can change it with the optional param ... --images-path=your/custom/path/here

  • media-path

💡 The default media path is content/media

You can change it with the optional param ... --media-path=your/custom/path/here

  • exclude-ext

💡 No default value, all extensions are included

You can exclude one or more file extensions. Examples:

  • Excluding .webp files, adding the optional param ... --exclude-ext=webp
  • Excluding .jpg and .gif files (add a comma), adding the optional param ... --exclude-ext=jpg,gif

🎯 Troubleshooting

Error: EACCES: permission denied, unlink ANY_FILE_PATH

Permissions issue on your server, try to run in your Ghost folder:

sudo chmod -R a+rw content

📋 Changelog

See CHANGELOG.md

👋 Credits

David Burgos from Ghostboard.io

👏 Contributors

✒️ License

See LICENSE file