Overview

Last updated: August 20th 2026

Super Images generates optimized image derivatives (WebP, AVIF, resized JPGs, and more) and serves them from your storage adapter — local disk or S3-compatible object storage.

You do not need the whole pipeline on day one. Start with a template tag, then add storage and CLI when you deploy.

1. Install

  1. Copy the add-on folder to system/user/addons/super_images.
  2. Keep vendor/ inside that folder (AWS SDK and php-vips bindings ship with the zip).
  3. Copy config:
cp system/user/addons/super_images/config/super_images.example.php \
   system/user/config/super_images.php

4. Install Super Images from Add-ons in the Control Panel. After upgrades, Update the add-on so new actions and hooks register.

Check the install from the ExpressionEngine system directory:
php eecli.php super_images:doctor
php eecli.php super_images:status

2. Output your first image

{exp:super_images:image
  src="{file:1:url}"
  profile="responsive"
  variant="md"
  format="webp"
  alt="Hero"
  class="rounded-lg"
  loading="lazy"
}
Or pass a File ID:
{exp:super_images:image file_id="1" variant="md" format="webp" alt="Hero"}

With default settings, missing files are generated during the page request and the <img> gets a storage URL.

3. Choose where files live

Local (simplest for development):
'storage' => [
    'default' => 'local',
    'adapters' => [
        'local' => [
            'type' => 'local',
            'path' => '{site_path}transforms/super-images',
            'baseUrl' => '{site_url}transforms/super-images',
        ],
    ],
],

S3 / Spaces / R2: see Storage. Put keys in environment variables, never in the example file or in git.

4. Pre-generate for production

Do not rely on the first page hit if you have many transforms:
php eecli.php super_images:generate --upload-dir=images --dry-run
php eecli.php super_images:generate --upload-dir=images --queue
php eecli.php super_images:generate --file=1

--queue requires a compatible queue add-on (for example BoldMinded Queue). Without it, generation runs inline.


5. Try the interactive demo

Templates live in the site, not the add-on zip:
system/user/templates/default_site/super-images.group

Sync the group in the CP template manager if the filesystem is not auto-discovered, then open /super-images. Allow picsum.photos for the portable CDN sample.

Common questions

Where are transforms stored?
On the configured adapter (local, s3, …). Not inside File Manager folders unless you point an adapter there.

Libvips errors about libvips.42.dylib ?
The PHP binding can be present while the native library is missing. With driver => auto, Super Images probes the dylib and falls back to Imagick, then GD. See Drivers.

Why is my CDN URL 404 but CLI says generated?
baseUrl must match the bucket you upload to. After switching adapters, run php eecli.php super_images:cleanup --all --dry-run then regenerate. See Storage.

Why are cache hits slow (~300 ms) on remote storage?
For S3-compatible adapters, Super Images checks small local existence markers first (default under {cache_path}super_images/markers). When markers are missing or stale — for example after switching storage backends — it falls back to a remote object check (doesObjectExist), which adds latency. Run cleanup + regenerate once so markers match the current adapter. Local disk adapters use a filesystem stat and are typically ~0–10 ms. See Storage — markers.

Custom CDN or optimizer?
Copy the starter classes in examples/.

Next reads