---
title: "Extension Configuration"
manual: "Imaginator"
version: "1.0"
permalink: "https://docs.typo3.org/permalink/schliesser/imaginator:configuration-settings@1.0"
source: "Configuration/ExtensionConfiguration.rst"
rendered: "2026-10-13T11:21:40+00:00"
---

# Extension Configuration {#configuration-settings}

All settings below are read from the instance-wide Extension Configuration. The
external-provider keys (`processor*`) are shared by every offloaded processor
and documented with the [processors](https://docs.typo3.org/permalink/schliesser/imaginator:configuration-processors@1.0).

## Settings {#settings}

-   **processor**

    -   *Type:* string
    -   *Default:* `local:async`

    Image processor: `local:async` (signed endpoint middleware),
    `local:sync` (static `srcset`, no middleware), `imgproxy` or
    `imagor` (offloaded). See [Processors](https://docs.typo3.org/permalink/schliesser/imaginator:configuration-processors@1.0).

-   **maxDimension**

    -   *Type:* integer
    -   *Default:* `3840`

    Largest image dimension in pixels. The width ladder is capped to this value.

-   **fixedHeightDprCap**

    -   *Type:* integer
    -   *Default:* `3`

    Highest device pixel ratio a [fixed-height tier](https://docs.typo3.org/permalink/schliesser/imaginator:usage-fixed-height@1.0)
    ships a `min-resolution` `<source>` for. `3` emits 1×/2×/3× tiers; `2`
    drops the 3× tier; `1` disables per-DPR sources (single 1× height).

-   **ladder**

    -   *Type:* string
    -   *Default:* `320,420,560,740,980,1300,1720,2000,2560,3200,3840`

    Width-ladder rungs (comma-separated px). An arbitrary requested width is
    quantized **up** to the nearest rung, which bounds the number of processed
    files and the set of signable URLs. The default ladder covers everything
    from small phones up to 4K (UHD) displays.

-   **breakpoints**

    -   *Type:* string
    -   *Default:* `xs:0,sm:576,md:768,lg:992,xl:1200`

    Design-system breakpoints (`alias:min-width` px) used to resolve a
    per-breakpoint aspect-ratio map. `xs:0` is the base ratio.

-   **format**

    -   *Type:* string
    -   *Default:* `avif`

    The output format (`avif` or `webp`) applied uniformly to the
    `<img>` and every `<source>`.

-   **quality.avif**

    -   *Type:* integer
    -   *Default:* `50`

    AVIF quality. AVIF's scale sits lower than JPEG / WebP for the same
    perceived quality.

-   **quality.webp**

    -   *Type:* integer
    -   *Default:* `72`

    WebP quality.

-   **lqip**

    -   *Type:* string
    -   *Default:* `thumbhash`

    Low-quality image placeholder. One of `thumbhash`, `dominant-color` or
    `none`. See [Content Security Policy](https://docs.typo3.org/permalink/schliesser/imaginator:configuration-csp@1.0).

-   **excludeExtensions**

    -   *Type:* string
    -   *Default:* `svg,ai,eps,gif`

    File extensions served verbatim as a plain `<img>`, never processed
    (vector / animated formats that carry no meaningful width ladder).

-   **processorBaseUrl**

    -   *Type:* string
    -   *Default:* (empty)

    External providers only: base URL of the provider endpoint (e.g.
    `https://imgproxy.example`). See [Offloaded processing with imgproxy](https://docs.typo3.org/permalink/schliesser/imaginator:configuration-imgproxy@1.0) and
    [Offloaded processing with imagor](https://docs.typo3.org/permalink/schliesser/imaginator:configuration-imagor@1.0).

-   **processorSignKey**

    -   *Type:* string
    -   *Default:* (empty)

    External providers only: HMAC **key**. Encoding is provider-specific —
    imgproxy expects a hex-encoded key, imagor the plain `IMAGOR_SECRET`
    string. Empty → unsigned URLs (`insecure` / `unsafe`, dev only).

-   **processorSalt**

    -   *Type:* string
    -   *Default:* (empty)

    imgproxy only: HMAC **salt** (hex). imagor's scheme has no salt — leave
    empty there.

-   **processorSourceBaseUrl**

    -   *Type:* string
    -   *Default:* (empty)

    External providers only: origin prefix prepended to the source path. Leave
    empty when the provider resolves relative paths itself (imgproxy:
    `IMGPROXY_BASE_URL`; imagor: `HTTP_LOADER_BASE_URL` /
    `HTTP_LOADER_DEFAULT_SCHEME` \+ allowed sources).

-   **processorOptions**

    -   *Type:* array of string
    -   *Default:* (empty)

    Provider-specific extras passed through to the URL builder (e.g. a
    Cloudflare account hash). Not in the backend form — set it in
    [`config/system/settings.php`](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/Configuration/Typo3ConfVars/Index.html#file-project-config-system-settings-php) under
    `$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['imaginator']['processorOptions']`.
    Builders consume what they need and ignore the rest; see
    [Custom Processor](https://docs.typo3.org/permalink/schliesser/imaginator:extend-custom-processor@1.0).

    This map only feeds builders registered **without** `extensionKey`. A
    provider shipped as its own extension declares
    `#[AsImaginatorProcessor('my-cdn', extensionKey: 'my_cdn')]` and keeps
    its options in its **own** Extension Configuration namespace instead —
    with its own [`ext_conf_template.txt`](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/FileStructure/ExtConfTemplate.html#file-extension-ext-conf-template-txt) and backend form.

## Signing {#configuration-signing}

The signing secret is derived from the global `encryptionKey`. When the
encryption key changes, flush the frontend caches. Re-rendered HTML then
carries URLs signed with the new key.