Skip to main content

Loader, Storage, Result Storage

imagor Loader, Storage and Result Storage are the building blocks for loading and saving images from various sources:

  • Loader loads source images.
  • Storage loads and saves source images for reuse on later requests.
  • Result Storage loads and saves processed images for reuse on later requests.

imagor provides built-in adaptors that support HTTP(s), Proxy, File System, AWS S3 and Google Cloud Storage. By default, HTTP Loader is used as fallback. You can choose to enable additional adaptors that fit your use cases.

Loader​

  • HTTP Loader — Default loader for remote HTTP/HTTPS images

Storage​

  • File System — Local file system storage using mounted volumes
  • AWS S3 — Amazon S3 and S3-compatible storage (Cloudflare R2, MinIO, DigitalOcean Spaces)
  • Google Cloud Storage — Google Cloud Storage buckets

Storage Key Normalization​

imagor normalizes image keys before passing them to File System, S3, or Google Cloud Storage.

By default, imagor preserves alphanumeric characters, /, and the standard unreserved URL characters -, _, ., and ~. Other characters are escaped unless you allow them with the backend-specific safe chars setting.

This keeps storage keys portable across backends, but literal filenames or object keys containing reserved characters such as [ and ] will not match unless those characters are configured as safe.

Use the backend-specific safe chars setting to preserve additional literal characters:

For example, to preserve literal brackets in source keys:

FILE_SAFE_CHARS=[]
S3_SAFE_CHARS=[]
GCLOUD_SAFE_CHARS=[]

To disable escaping entirely, set the safe chars value to --.

FILE_SAFE_CHARS=--
S3_SAFE_CHARS=--
GCLOUD_SAFE_CHARS=--

Storage and Result Storage Path Style​

Enables additional hashing rules to the storage key when loading and saving images. Accepts original (default), digest, suffix, or size.

Skipping Storage by Prefixes​

Storage saves an image the first time a loader returns it, so later requests reuse the copy. IMAGOR_STORAGE_SKIP_PREFIXES lists image prefixes that are read in place instead: imagor loads them from their origin and neither reads nor writes Storage.

IMAGOR_STORAGE_SKIP_PREFIXES=museado/,nara/
  • Prefixes match whole path parts: museado covers museado/a.jpg, not museado2/a.jpg.
  • Applies to every loader — S3, Google Cloud Storage, File System, and HTTP.
  • Copies already in Storage for these prefixes are ignored; normal expiry or lifecycle rules clean them up.
  • Result Storage is unaffected.
  • IMAGOR_MODIFIED_TIME_CHECK stats Storage, so skipped prefixes serve cached results without revalidation.