Skip to content

IMG-140: c2pa docs, source cache docs #16

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gzigzigzeo wants to merge 2 commits into from
Open

IMG-140: c2pa docs, source cache docs #16

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
65d81f1
IMG-140: c2pa docs, source cache docs
gzigzigzeo Sep 14, 2026
dd8e7e6
Corrected _INFERENCE_ vars
gzigzigzeo Sep 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 50 additions & 4 deletions docs/cache/internal.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,14 @@ You need to define the following config variables to enable the internal cache:
* [`IMGPROXY_CACHE_KEY_HEADERS`]: _(optional)_ a list of HTTP request headers (comma-separated) to include in the cache key. This allows caching different versions of the same image based on request headers. Default: blank
* [`IMGPROXY_CACHE_KEY_COOKIES`]: _(optional)_ a list of HTTP request cookies (comma-separated) to include in the cache key. This allows caching different versions of the same image based on cookies. Default: blank
* [`IMGPROXY_CACHE_REPORT_ERRORS`]: When `true`, imgproxy will report cache errors instead of silently falling back to processing without cache. Default: `false`
* [`IMGPROXY_CACHE_SHUTDOWN_TIMEOUT`]: _(optional)_ the maximum time imgproxy will wait for pending background cache writes to complete during a graceful shutdown. Default: `5s`
* [`IMGPROXY_CACHE_PROCESSING_ENABLED`]: _(optional)_ when `true`, imgproxy will cache processed images. Default: `true`
* [`IMGPROXY_CACHE_INFO_ENABLED`]: _(optional)_ when `true`, imgproxy will cache `/info` endpoint responses. Default: `true`
* [`IMGPROXY_CACHE_SOURCE_ENABLE`]: _(optional)_ when `true`, imgproxy caches downloaded source images in addition to processed results. Default: `false`

### Source image caching

In addition to caching processed results, imgproxy can cache the raw bytes of downloaded source images. Set `IMGPROXY_CACHE_SOURCE_ENABLE` to `true` to enable it. This is useful when you request the same source image with many different processing options. Instead of re-downloading the source for every variant, imgproxy fetches it once and serves subsequent requests from the cache.

### Storage configuration

Expand All @@ -42,7 +50,7 @@ Configure the storage backend using `IMGPROXY_CACHE_*` variables:

## Cache key

The cache key is generated based on:
The cache key for processed images and `/info` responses is generated based on:

* Source image URL
* Processing options
Expand All @@ -52,17 +60,55 @@ The cache key is generated based on:

URL signature is **not** part of the cache key, allowing key rotation without invalidating the cache.

### Source cache key

When [source image caching](#source-image-caching) is enabled, cached sources use their own separate key, based on:

* Source image URL
* Optional: Request headers specified in `IMGPROXY_CACHE_KEY_HEADERS`
* Optional: Request cookies specified in `IMGPROXY_CACHE_KEY_COOKIES`

Unlike the processed-image cache key, it doesn’t include processing options or the output format because it stores the downloaded source image, not a processed variant. It also doesn’t include the [cachebuster](../usage/processing.mdx#cache-buster) value, so busting the processed-image cache doesn't invalidate the cached source.

## Cache tags

imgproxy Pro can attach cache tags to a cache entry using the [cache_tags](../usage/processing.mdx#cache-tags) processing option:

```imgproxy_url_option
cache_tags:%tag1:%tag2:...:%tagN
ct:%tag1:%tag2:...:%tagN
```

Each tag can be up to 256 characters long and must consist of visible ASCII characters (character codes 33-126), excluding commas. We consider at most 50 tags per request; any beyond that are silently dropped.

The tags are also written to the response headers, so a CDN in front of imgproxy can use them for tag-based cache invalidation. Use the [`IMGPROXY_CACHE_TAGS_FORMAT`](../configuration/options.mdx#IMGPROXY_CACHE_TAGS_FORMAT) config to choose which format(s) the tags are written in — [CloudFront](https://aws.amazon.com/blogs/networking-and-content-delivery/manage-caches-with-precision-using-amazon-cloudfront-invalidation-by-cache-tag/), [Cloudflare](https://developers.cloudflare.com/cache/how-to/purge-cache/purge-by-tags/), both (the default), or neither.

## Bypassing the cache

imgproxy Pro can bypass the internal cache for a single request using the [bypass_cache](../usage/processing.mdx#bypass-cache) processing option:

```imgproxy_url_option
bypass_cache:%bypass
bc:%bypass
```

When enabled for a request, imgproxy skips reading and writing the cache entirely—including the source cache, if enabled—and processes and fetches everything from the source image. Because this lets a client bypass your cache, it’s not allowed unless the [`IMGPROXY_ALLOW_BYPASS_CACHE`](../configuration/options.mdx#IMGPROXY_ALLOW_BYPASS_CACHE) config is set to `true`.

## Limitations

* **No manual cache invalidation**: Currently, imgproxy doesn't provide a built-in means to invalidate the cache. However, imgproxy includes the [cachebuster](../usage/processing.mdx#cache-buster) in the cache key, so you can use it to force cache invalidation when needed. Most storage offerings also support object expiration, so you can set a reasonable expiration time for cached images.
* **No cache for info requests**: The internal cache is currently used only for image processing requests. Requests to the `/info` endpoint are not cached.

## How it works

When a request comes in:

1. imgproxy checks the URL signature (if enabled).
2. imgproxy generates the cache key from the request parameters.
3. imgproxy checks if a cached image exists in the configured storage.
3. imgproxy checks if a cached processed image exists in the configured storage.
4. If the cached image exists and is valid, imgproxy serves it directly.
5. If not, imgproxy processes the image and stores the result in the cache before serving it.
5. If not, and [source image caching](#source-image-caching) is enabled, imgproxy checks the source cache (using its own [separate key](#source-cache-key)) before downloading the source image:
* On a hit, imgproxy uses the cached source bytes instead of re-downloading them.
* On a miss, imgproxy downloads the source image and caches it in the background.
6. imgproxy processes the image, serves the result, and stores it in the cache in the background — the response isn't delayed while it waits for the cache write to finish.

Cache writes (both processed-image and source) always happen in the background this way. On a graceful shutdown, imgproxy waits up to [`IMGPROXY_CACHE_SHUTDOWN_TIMEOUT`](../configuration/options.mdx#IMGPROXY_CACHE_SHUTDOWN_TIMEOUT) for any still-pending writes to finish before exiting.
52 changes: 36 additions & 16 deletions docs/configuration/options.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -278,10 +278,10 @@ Autoquality requires the image to be saved several times. Use it only when you p
* [`IMGPROXY_AUTOQUALITY_AVIF_NET`]: ((pro)) the path to the neural network model for AVIF.
* [`IMGPROXY_AUTOQUALITY_JXL_NET`]: ((pro)) the path to the neural network model for JPEG XL.

* [`IMGPROXY_AUTOQUALITY_ML_INFERENCE_NUM_STREAMS`]: ((pro)) when set, overrides the [IMGPROXY_ML_NUM_STREAMS](#IMGPROXY_ML_NUM_STREAMS) value for the autoquality models.
* [`IMGPROXY_AUTOQUALITY_ML_INFERENCE_NUM_STREAMS`]: ((pro)) when set, overrides the [IMGPROXY_ML_INFERENCE_NUM_STREAMS](#IMGPROXY_ML_INFERENCE_NUM_STREAMS) value for the autoquality models.
* [`IMGPROXY_AUTOQUALITY_ML_INFERENCE_NUM_THREADS`]: ((pro)) when set, overrides the [IMGPROXY_ML_INFERENCE_NUM_THREADS](#IMGPROXY_ML_INFERENCE_NUM_THREADS) value for the autoquality models.
* [`IMGPROXY_AUTOQUALITY_ML_EXECUTION_MODE`]: ((pro)) when set, overrides the [IMGPROXY_ML_EXECUTION_MODE](#IMGPROXY_ML_EXECUTION_MODE) value for the autoquality models.
* [`IMGPROXY_AUTOQUALITY_ML_CPU_PINNING`]: ((pro)) when set, overrides the [IMGPROXY_ML_CPU_PINNING](#IMGPROXY_ML_CPU_PINNING) value for the autoquality models.
* [`IMGPROXY_AUTOQUALITY_ML_INFERENCE_EXECUTION_MODE`]: ((pro)) when set, overrides the [IMGPROXY_ML_INFERENCE_EXECUTION_MODE](#IMGPROXY_ML_INFERENCE_EXECUTION_MODE) value for the autoquality models.
* [`IMGPROXY_AUTOQUALITY_ML_INFERENCE_CPU_PINNING`]: ((pro)) when set, overrides the [IMGPROXY_ML_INFERENCE_CPU_PINNING](#IMGPROXY_ML_INFERENCE_CPU_PINNING) value for the autoquality models.

## SVG processing
* [`IMGPROXY_ALWAYS_RASTERIZE_SVG`]: when `true`, imgproxy will always rasterize SVG images unless SVG processing is not [skipped](#skip-processing). Default: `false`
Expand Down Expand Up @@ -413,6 +413,20 @@ imgproxy Pro can process digital camera RAW images. Since loading RAW images is

Read more about watermarks in the [Watermark](../features/watermark.mdx) guide.

## C2PA

imgproxy can attach [C2PA](https://c2pa.org/) content provenance manifests to processed images.

* [`IMGPROXY_C2PA_ENABLED`]: ((pro)) when `true`, imgproxy will sign processed images with a C2PA manifest. Default: `false`
* [`IMGPROXY_C2PA_SETTINGS`]: ((pro)) the raw c2pa-rs SDK settings string, including signing credentials. Takes precedence over `IMGPROXY_C2PA_SETTINGS_PATH`
* [`IMGPROXY_C2PA_SETTINGS_PATH`]: ((pro)) the path to a file with the c2pa-rs SDK settings, as an alternative to `IMGPROXY_C2PA_SETTINGS`
* [`IMGPROXY_C2PA_FORMAT`]: ((pro)) the format of the C2PA settings. Can be `toml` or `json`. Default: `toml`
* [`IMGPROXY_C2PA_ACTION`]: ((pro)) the C2PA action recorded in the manifest for processed images. Default: `c2pa.edited`
* [`IMGPROXY_C2PA_SOFTWARE_AGENT`]: ((pro)) the software agent name recorded in the manifest. Default: `imgproxy`
* [`IMGPROXY_C2PA_SOFTWARE_AGENT_VERSION`]: ((pro)) the software agent version recorded in the manifest. Default: the running imgproxy version

Read more about C2PA in the [C2PA](../features/c2pa.mdx) guide.

## Unsharp masking

imgproxy Pro can apply unsharp masking to your images.
Expand All @@ -436,17 +450,17 @@ imgproxy Pro can apply unsharp masking to your images.

These options allow you to configure common aspects of machine learning features such as object detection, classification, autoquality, etc.

* [`IMGPROXY_ML_NUM_STREAMS`]: ((pro)) the maximum number of inference requests that can be processed concurrently by each machine learning model. When the limit is reached, additional inference requests will be queued until the previous ones are finished. Default: the number of CPU cores available to imgproxy
* [`IMGPROXY_ML_INFERENCE_NUM_STREAMS`]: ((pro)) the maximum number of inference requests that can be processed concurrently by each machine learning model. When the limit is reached, additional inference requests will be queued until the previous ones are finished. Default: the number of CPU cores available to imgproxy

:::tip
The larger the `IMGPROXY_ML_NUM_STREAMS` value, the more memory ML features will consume. If you don't have a lot of RAM, you may want to set it to a value lower than the number of CPU cores.
The larger the `IMGPROXY_ML_INFERENCE_NUM_STREAMS` value, the more memory ML features will consume. If you don't have a lot of RAM, you may want to set it to a value lower than the number of CPU cores.
:::

* [`IMGPROXY_ML_INFERENCE_NUM_THREADS`]: ((pro)) the number of threads that can be used for inference by each machine learning model. If less than the `IMGPROXY_ML_NUM_STREAMS` value, the number of streams will be limited to this value. Default: the number of CPU cores available to imgproxy
* [`IMGPROXY_ML_EXECUTION_MODE`]: ((pro)) the execution mode of the machine learning models. Supported values are:
* [`IMGPROXY_ML_INFERENCE_NUM_THREADS`]: ((pro)) the number of threads that can be used for inference by each machine learning model. If less than the `IMGPROXY_ML_INFERENCE_NUM_STREAMS` value, the number of streams will be limited to this value. Default: the number of CPU cores available to imgproxy
* [`IMGPROXY_ML_INFERENCE_EXECUTION_MODE`]: ((pro)) the execution mode of the machine learning models. Supported values are:
* `performance`: _(default)_ the model will be optimized for performance. Some model layers may be fused or converted to a different type to improve performance. This may lead to a slight decrease in accuracy.
* `accuracy`: the model will be optimized for accuracy. The optimizations that may decrease accuracy will be disabled. This may lead to decreased performance.
* [`IMGPROXY_ML_CPU_PINNING`]: ((pro)) when `true`, machine learning inference threads will be pinned to CPU cores. This may improve performance on some workloads, but generally it is not recommended to enable this option. Default: `false`
* [`IMGPROXY_ML_INFERENCE_CPU_PINNING`]: ((pro)) when `true`, machine learning inference threads will be pinned to CPU cores. This may improve performance on some workloads, but generally it is not recommended to enable this option. Default: `false`

## Object detection

Expand All @@ -465,10 +479,10 @@ imgproxy can detect objects on the image and use them to perform smart cropping,
* `one_best`: in this mode, imgproxy will focus on the object with the highest score based on its area, confidence, and class weight.
* `one_best_centermost`: the same as `one_best,` but imgproxy will add the object's proximity to the image center to its score.

* [`IMGPROXY_OBJECT_DETECTION_ML_INFERENCE_NUM_STREAMS`]: ((pro)) when set, overrides the [IMGPROXY_ML_NUM_STREAMS](#IMGPROXY_ML_NUM_STREAMS) value for the object detection model.
* [`IMGPROXY_OBJECT_DETECTION_ML_INFERENCE_NUM_THREADS`]: ((pro)) when set, overrides the [IMGPROXY_ML_INFERENCE_NUM_THREADS](#IMGPROXY_ML_INFERENCE_NUM_THREADS) value for the object detection model.
* [`IMGPROXY_OBJECT_DETECTION_ML_EXECUTION_MODE`]: ((pro)) when set, overrides the [IMGPROXY_ML_EXECUTION_MODE](#IMGPROXY_ML_EXECUTION_MODE) value for the object detection model.
* [`IMGPROXY_OBJECT_DETECTION_ML_CPU_PINNING`]: ((pro)) when set, overrides the [IMGPROXY_ML_CPU_PINNING](#IMGPROXY_ML_CPU_PINNING) value for the object detection model.
* [`IMGPROXY_OBJECT_DETECTION_INFERENCE_NUM_STREAMS`]: ((pro)) when set, overrides the [IMGPROXY_ML_INFERENCE_NUM_STREAMS](#IMGPROXY_ML_INFERENCE_NUM_STREAMS) value for the object detection model.
* [`IMGPROXY_OBJECT_DETECTION_INFERENCE_NUM_THREADS`]: ((pro)) when set, overrides the [IMGPROXY_ML_INFERENCE_NUM_THREADS](#IMGPROXY_ML_INFERENCE_NUM_THREADS) value for the object detection model.
* [`IMGPROXY_OBJECT_DETECTION_INFERENCE_EXECUTION_MODE`]: ((pro)) when set, overrides the [IMGPROXY_ML_INFERENCE_EXECUTION_MODE](#IMGPROXY_ML_INFERENCE_EXECUTION_MODE) value for the object detection model.
* [`IMGPROXY_OBJECT_DETECTION_INFERENCE_CPU_PINNING`]: ((pro)) when set, overrides the [IMGPROXY_ML_INFERENCE_CPU_PINNING](#IMGPROXY_ML_INFERENCE_CPU_PINNING) value for the object detection model.

Read the [Object Detection guide](../features/object_detection.mdx) for more info.

Expand All @@ -489,10 +503,10 @@ imgproxy can classify images by assigning them to predefined categories based on
* `nhwc`: _(default)_ channels last (TensorFlow default)
* `nchw`: channels first (PyTorch default)

* [`IMGPROXY_CLASSIFICATION_ML_INFERENCE_NUM_STREAMS`]: ((pro)) when set, overrides the [IMGPROXY_ML_NUM_STREAMS](#IMGPROXY_ML_NUM_STREAMS) value for the classification model.
* [`IMGPROXY_CLASSIFICATION_ML_INFERENCE_NUM_THREADS`]: ((pro)) when set, overrides the [IMGPROXY_ML_INFERENCE_NUM_THREADS](#IMGPROXY_ML_INFERENCE_NUM_THREADS) value for the classification model.
* [`IMGPROXY_CLASSIFICATION_ML_EXECUTION_MODE`]: ((pro)) when set, overrides the [IMGPROXY_ML_EXECUTION_MODE](#IMGPROXY_ML_EXECUTION_MODE) value for the classification model.
* [`IMGPROXY_CLASSIFICATION_ML_CPU_PINNING`]: ((pro)) when set, overrides the [IMGPROXY_ML_CPU_PINNING](#IMGPROXY_ML_CPU_PINNING) value for the classification model.
* [`IMGPROXY_CLASSIFICATION_INFERENCE_NUM_STREAMS`]: ((pro)) when set, overrides the [IMGPROXY_ML_INFERENCE_NUM_STREAMS](#IMGPROXY_ML_INFERENCE_NUM_STREAMS) value for the classification model.
* [`IMGPROXY_CLASSIFICATION_INFERENCE_NUM_THREADS`]: ((pro)) when set, overrides the [IMGPROXY_ML_INFERENCE_NUM_THREADS](#IMGPROXY_ML_INFERENCE_NUM_THREADS) value for the classification model.
* [`IMGPROXY_CLASSIFICATION_INFERENCE_EXECUTION_MODE`]: ((pro)) when set, overrides the [IMGPROXY_ML_INFERENCE_EXECUTION_MODE](#IMGPROXY_ML_INFERENCE_EXECUTION_MODE) value for the classification model.
* [`IMGPROXY_CLASSIFICATION_INFERENCE_CPU_PINNING`]: ((pro)) when set, overrides the [IMGPROXY_ML_INFERENCE_CPU_PINNING](#IMGPROXY_ML_INFERENCE_CPU_PINNING) value for the classification model.

Read the [Classification guide](../features/classification.mdx) for more info.

Expand All @@ -506,6 +520,10 @@ imgproxy can cache processed images in various storage backends to improve perfo
* [`IMGPROXY_CACHE_KEY_HEADERS`]: ((pro)) a comma-separated list of HTTP request headers to include in the cache key. This allows caching different versions of the same image based on request headers. Default: blank
* [`IMGPROXY_CACHE_KEY_COOKIES`]: ((pro)) a comma-separated list of HTTP request cookies to include in the cache key. This allows caching different versions of the same image based on cookies. Default: blank
* [`IMGPROXY_CACHE_REPORT_ERRORS`]: ((pro)) when `true`, imgproxy will report cache errors instead of silently falling back to processing without cache. Default: `false`
* [`IMGPROXY_CACHE_SHUTDOWN_TIMEOUT`]: ((pro)) the maximum time imgproxy will wait for pending background cache writes to complete during a graceful shutdown. Default: `5s`
* [`IMGPROXY_CACHE_PROCESSING_ENABLED`]: ((pro)) when `true`, imgproxy will cache processed images. Default: `true`
* [`IMGPROXY_CACHE_INFO_ENABLED`]: ((pro)) when `true`, imgproxy will cache `/info` endpoint responses. Default: `true`
* [`IMGPROXY_CACHE_SOURCE_ENABLE`]: ((pro)) when `true`, imgproxy will cache downloaded source image bytes in addition to processed results. Default: `false`

* [`IMGPROXY_CACHE_TAGS_FORMAT`]: ((pro)) defines how the cache tags added by the [cache_tags](../usage/processing.mdx#cache-tags) option are written to the response headers. Supported values are:
* `all`: _(default)_ imgproxy will write cache tags in all supported formats
Expand Down Expand Up @@ -771,6 +789,7 @@ imgproxy can send request traces to an OpenTelemetry collector:
* [`IMGPROXY_OPEN_TELEMETRY_CLIENT_KEY`]: OpenTelemetry client TLS key, PEM-encoded (you can replace line breaks with `\n`). Default: blank
* [`IMGPROXY_OPEN_TELEMETRY_TRACE_ID_GENERATOR`]: OpenTelemetry trace ID generator. Supported generators are `xray` and `random`. Default: `xray`
* [`IMGPROXY_OPEN_TELEMETRY_PROPAGATE_EXTERNAL`]: when `true`, imgproxy will propagate OpenTelemetry tracing headers to external requests such as image downloads. Default: `false`
* [`IMGPROXY_OPEN_TELEMETRY_LOGGER_NAME`]: the instrumentation scope name used when sending logs to the OpenTelemetry collector. Default: `imgproxy`

Check out the [OpenTelemetry](../monitoring/open_telemetry.mdx) guide to learn more.

Expand All @@ -789,6 +808,7 @@ Check out the [CloudWatch](../monitoring/cloud_watch.mdx) guide to learn more.
imgproxy can report occurred errors to Bugsnag, Honeybadger and Sentry:

* [`IMGPROXY_REPORT_DOWNLOADING_ERRORS`]: when `true`, imgproxy will report downloading errors. Default: `true`
* [`IMGPROXY_REPORT_IO_ERRORS`]: when `true`, imgproxy will report errors that occur while writing the response body to the client. Default: `false`
* [`IMGPROXY_DEVELOPMENT_ERRORS_MODE`]: when `true`, imgproxy will respond with detailed error messages and stack traces in a pretty HTML format. Useful for development and debugging. If the client does not `Accept: text/html`, imgproxy reponds with plain text error. Default: `false`

### Bugsnag
Expand Down
Loading
Loading