Image Derivative Storage

Image Derivative Storage keeps the resized and cropped copies of your images (image style derivatives) in their own folder, separate from uploaded files.

When Drupal shows an image using an image style, such as a thumbnail or a banner crop, it creates a new copy of the image and saves it next to your original uploads in the public files directory. That's fine on a simple server. But if your files live on network storage, such as an SMB/CIFS share, NFS, Azure Files, Amazon EFS or GlusterFS, writing and deleting these copies can be slow or fail. Clearing image styles then produces errors. This module moves only those generated copies to a separate location, such as fast local disk. Your original files stay where they are.

Features

• Adds a new file location, derivatives://, which works like the public files directory but has its own folder (sites/default/derivatives by default).
• Image style derivatives are saved there instead of in public://styles. Missing derivatives are still generated on first request, the same way as in core.
• Choose which file locations to relocate (public by default). Derivatives of private files are never moved, so they are never exposed publicly.
• Optional: never delete from chosen locations when image styles are flushed. Useful when deletes on network storage are unreliable.
• Optional: serve derivatives from a different host, such as a CDN.
• Status report checks for a missing or unwritable folder, missing settings, and conflicts with other modules.

When to use it:

• Your public files are on a network share and flushing image styles is slow or fails with errors such as unlink(): No such file or directory.
• You run in containers or on several web servers and want derivatives on local or temporary disk. They can always be regenerated, so they don't need shared, backed-up storage.
• You want to keep regenerable files out of backups and file syncs of your uploads.

Post-Installation

1. Enable the module. It creates the derivative folder and works right away with the default settings.
2. Add this to settings.php so derivatives are served with public cache headers:
   

   $settings['file_additional_public_schemes'] = ['derivatives'];

3. Optional: choose a different folder (it must be web-accessible), then rebuild caches:
   

   $settings['image_derivative_storage_path'] = 'sites/default/derivatives';

4. Optional: go to Administration » Configuration » Media » Image derivative storage (/admin/config/media/image-derivative-storage) to choose which locations are relocated and which are never deleted from on flush.
5. Check Reports » Status report for any configuration problems.

Web server: the standard Drupal Apache and Nginx configurations already send requests for missing files to Drupal, so derivatives are generated on demand. If your Nginx configuration has special rules for sites/*/files, add the same rule for the derivative folder. See the README for an example.

Existing sites: old derivatives in public://styles are no longer used. If you set the module to never delete from public files on flush, delete that folder manually once.

Additional Requirements

• Drupal 11.2 or later.
• The core Image module.

No external libraries or services are required.

Recommended modules/libraries

• CDN: serve files, including derivatives, from a content delivery network.
• Image Style Warmer: generate derivatives in advance, useful after moving them to empty storage.

Similar projects

• S3 File System and Flysystem move your file storage (originals and derivatives) to remote or cloud storage. Image Derivative Storage does the opposite: it keeps originals where they are and moves only the regenerable derivatives, usually to local disk.

Known limitations

• The module replaces the image style entity class. Only one module can do this. If another module already does, this module stays inactive and the status report says so.
• Uninstalling deletes the derivative folder. Derivatives are then regenerated in their normal locations on demand.