Backdrop normally creates an image style derivative the first time a page requests it. This module creates those derivatives ahead of time, so visitors do not have to wait for image processing on the first request.
It works with Backdrop image styles and permanent managed image files. It uses
Backdrop's image APIs and stream wrappers, so it supports public files,
private files, and remote storage such as S3 through the s3fs module.
Go to Configuration > Media > Image Style Warmer:
admin/config/media/image-style-warmer
The page lists every image style and provides three settings.
When a new image becomes permanent, the selected styles are generated during the same request that saves the image.
Use this for a small number of important styles, such as the thumbnail shown immediately after an upload. The image upload takes longer because the image processing happens before the request finishes, but the derivative is ready as soon as the upload completes.
When a new image becomes permanent, the selected styles are added to the
image_style_warmer_derivatives queue. Backdrop cron processes that queue for
up to 60 seconds per cron run.
Use this for larger images, many styles, slower storage, or styles that do not need to be available immediately. The upload stays responsive, but the derivative is not guaranteed to exist until cron has processed the queue.
If cron is not running, queued derivatives remain pending. They can be run manually with:
bee image_style_queue_run
A style selected for immediate warming is automatically removed from the queued set for that upload, preventing duplicate work.
This is enabled by default. Rebuild operations check whether the derivative already exists and leave it alone when it does.
Disable this setting to make the default rebuild behavior regenerate existing
derivatives. Individual rebuild operations also provide a Force
regeneration checkbox, and the command-line rebuild supports --force.
The image styles page has a Rebuild link beside each style:
admin/config/media/image-styles
There is also a Rebuild all styles action. Rebuilds scan permanent image files and use a batch process so large libraries can be handled over multiple requests. The batch processes 20 files at a time for each style and reports processed and failed files when it finishes.
The command-line equivalent is:
- Rebuild every image style:
bee image_style_rebuild - Rebuild one style by machine name:
bee image_style_rebuild --style=thumbnail - Regenerate derivatives even when they already exist:
bee image_style_rebuild --forceorbee image_style_rebuild --style=thumbnail --force - Process only one file for the style:
bee image_style_rebuild --style=thumbnail --limit=1
The command is also available as bee isr.
The rebuild command accepts --limit per style; zero or an omitted value means
that all matching permanent image files are processed.
The queue runner processes items that were created by the background upload setting or by the bulk action:
- Process for up to 60 seconds with no item limit:
bee image_style_queue_run - Process for up to two minutes:
bee image_style_queue_run --time=120 - Process at most 500 items:
bee image_style_queue_run --limit=500 - Apply both limits:
bee isqr --time=120 --limit=500
If derivative creation fails, the item remains available for a later retry. The command reports the number of processed and failed items. A missing image style is logged and discarded because it represents stale configuration.
The module provides a file action named Warm all image styles. On the Manage files page, select one or more image files, choose this action, and click Execute. It synchronously generates every defined image style for each selected file, skipping derivatives that already exist when that option is enabled. On a file listing or View that supports Backdrop bulk actions, select one or more image files and apply that action. It uses the configured immediate and background style lists:
- Styles configured for immediate warming are generated while the action runs.
- Styles configured for background warming are added to the queue.
This is useful after importing images, before launching a new image-heavy page, or when only a selected group of files needs to be prepared.
The module warms only permanent files whose MIME type starts with image/.
It handles both direct permanent file saves and the common managed-file
workflow where an uploaded file is temporary first and becomes permanent when
the parent content is saved.
Configuration and rebuild pages require the Administer image styles permission. The bulk warming action uses the same permission.
The module does not automatically re-warm derivatives when Manual Crop crop coordinates change. Manual Crop saves crop selections in its own submit handler and does not expose a reliable crop-change hook in this Backdrop version. Use the rebuild action or the bulk warming action after changing existing crop selections.
This module requires that the following module is also enabled:
- Image module
- Install this module using the official Backdrop CMS instructions at https://docs.backdropcms.org/documentation/extend-with-modules.
Bugs and Feature Requests should be reported in the Issue Queue: https://github.com/backdrop-contrib/image_style_warmer/issues.
- Inspired by the Drupal module of the same name, https://www.drupal.org/project/image_style_warmer.
- Developed with AI assistance.
This project is GPL v2 software. See the LICENSE.txt file in this directory for complete text.