# Internal cache ((pro))

imgproxy Pro provides an internal cache that stores processed images on disk or in cloud storage. This cache can act as both a primary and a secondary cache, serving as a fallback when your CDN cache misses.

:::tip
While putting a CDN in front of imgproxy is and will always be a best practice, the internal cache provides long-term storage for cases that require an additional caching layer.
:::

## Why use internal cache?

The internal cache provides long-term persistent storage for processed images, unlike CDNs, which typically delete rarely accessed content. It stores images in a single location rather than across multiple edge stores, eliminating cache misses when requests hit different edges. The cache is designed specifically for imgproxy, working seamlessly with features like modern image format detection and client hints support that generic external caches don't understand by default.

The cache is protected by the same security measures as imgproxy itself, including URL signatures and processing restrictions. Importantly, URL signatures are not part of the cache key, so you can rotate keys or use multiple key/salt pairs without invalidating cached images. You maintain full control over where the cache is stored and how it integrates with your infrastructure.

## Configuration

You need to define the following config variables to enable the internal cache:

* [`IMGPROXY_CACHE_USE`]: the cache storage adapter to use. Can be `fs`, `s3`, `gcs`, `abs` (Azure Blob Storage), or `swift` (OpenStack Swift). When blank, the cache is disabled. Default: blank
* [`IMGPROXY_CACHE_PATH_PREFIX`]: _(optional)_ a path prefix for the cache files. This can be useful to organize cache files in a specific directory structure. Default: blank
* [`IMGPROXY_CACHE_BUCKET`]: _(optional)_ the bucket name for cloud storage adapters (S3, GCS, ABS, Swift). When using the filesystem adapter, this can be used as an additional path component. Default: blank
* [`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

The internal cache supports all the storage backends that imgproxy can read source images from: local filesystem, Amazon S3 and compatible services (Cloudflare R2, DigitalOcean Spaces, MinIO, etc.), Google Cloud Storage, Microsoft Azure Blob Storage, and OpenStack Swift.

Configure the storage backend using `IMGPROXY_CACHE_*` variables:

* For filesystem cache, see [Cache storage: Local filesystem](./internal/local_filesystem.mdx).
* For S3 cache, see [Cache storage: Amazon S3](./internal/amazon_s3.mdx).
* For GCS cache, see [Cache storage: Google Cloud Storage](./internal/google_cloud_storage.mdx).
* For Azure Blob Storage cache, see [Cache storage: Azure Blob Storage](./internal/azure_blob_storage.mdx).
* For Swift cache, see [Cache storage: OpenStack Object Storage ("Swift")](./internal/openstack_swift.mdx).

## Cache key

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

* Source image URL
* Processing options
* Output format
* Optional: Request headers specified in `IMGPROXY_CACHE_KEY_HEADERS`
* Optional: Request cookies specified in `IMGPROXY_CACHE_KEY_COOKIES`

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.

## 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 processed image exists in the configured storage.
4. If the cached image exists and is valid, imgproxy serves it directly.
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.

---

## Navigation

- [Getting started](/latest/getting_started)
- [imgproxy Pro](https://imgproxy.net#pro)
- [Installation](/latest/installation)
- [Configuration](/latest/category/configuration)
  - [Configuration options](/latest/configuration/options)
  - [Loading environment variables](/latest/configuration/loading_environment_variables)
- [Usage](/latest/category/usage)
  - [Processing an image](/latest/usage/processing)
  - [Getting an image info](/latest/usage/getting_info)
  - [Signing a URL](/latest/usage/signing_url)
  - [Encrypting a source URL](/latest/usage/encrypting_source_url)
  - [Presets](/latest/usage/presets)
- [Features](/latest/category/features)
  - [Watermark](/latest/features/watermark)
  - [Object detection](/latest/features/object_detection)
  - [Classification](/latest/features/classification)
  - [Autoquality](/latest/features/autoquality)
  - [Best format](/latest/features/best_format)
  - [Chained pipelines](/latest/features/chained_pipelines)
  - [Video thumbnails](/latest/features/video_thumbnails)
    - [Hardware acceleration](/latest/features/hardware_acceleration)
  - [C2PA](/latest/features/c2pa)
- [Image sources](/latest/category/image-sources)
  - [Serving local files](/latest/image_sources/local_files)
  - [Serving files from Amazon S3](/latest/image_sources/amazon_s3)
  - [Serving files from Google Cloud Storage](/latest/image_sources/google_cloud_storage)
  - [Serving files from Azure Blob Storage](/latest/image_sources/azure_blob_storage)
  - [Serving files from OpenStack Object Storage ("Swift")](/latest/image_sources/openstack_swift)
- [Cache](/latest/category/cache)
  - [External cache](/latest/cache/external)
  - [Internal cache](/latest/cache/internal)
    - [Internal cache: Local filesystem](/latest/cache/internal/local_filesystem)
    - [Internal cache: Amazon S3](/latest/cache/internal/amazon_s3)
    - [Internal cache: Google Cloud Storage](/latest/cache/internal/google_cloud_storage)
    - [Internal cache: Azure Blob Storage](/latest/cache/internal/azure_blob_storage)
    - [Internal cache: OpenStack Object Storage ("Swift")](/latest/cache/internal/openstack_swift)
- [Monitoring](/latest/category/monitoring)
  - [New Relic](/latest/monitoring/new_relic)
  - [Prometheus](/latest/monitoring/prometheus)
  - [Datadog](/latest/monitoring/datadog)
  - [OpenTelemetry](/latest/monitoring/open_telemetry)
  - [Amazon CloudWatch](/latest/monitoring/cloud_watch)
- [Image formats support](/latest/image_formats_support)
- [About the processing pipeline](/latest/about_processing_pipeline)
- [Health check](/latest/healthcheck)
- [Memory usage tweaks](/latest/memory_usage_tweaks)

## Other versions

- [4.0.x (current)](/cache/internal)