Skip to content

options.mdx

Latest commit

 

History

History
812 lines (569 loc) · 61.3 KB

options.mdx

File metadata and controls

812 lines (569 loc) · 61.3 KB
description Learn about imgproxy's configuration options

Configuration options

imgproxy is Twelve-Factor-App-ready and can be configured using ENV variables.

URL signature

imgproxy allows URLs to be signed with a key and a salt. This feature is disabled by default, but is highly recommended to be enabled in production. To enable URL signature checking, define the key/salt pair:

  • [IMGPROXY_KEY]: hex-encoded key
  • [IMGPROXY_SALT]: hex-encoded salt
  • [IMGPROXY_SIGNATURE_SIZE]: number of bytes to use for signature before encoding to Base64. Default: 32

You can specify multiple key/salt pairs by dividing the keys and salts with a comma (,). imgproxy will check URL signatures with each pair. This is useful when you need to change key/salt pairs in your application while incurring zero downtime.

If you need a random key/salt pair really fast, as an example, you can quickly generate one using the following snippet:

echo $(xxd -g 2 -l 64 -p /dev/random | tr -d '\n')
  • [IMGPROXY_TRUSTED_SIGNATURES]: a list of trusted signatures, comma divided. When set, imgproxy will trust the signatures from the list and won't check them even if IMGPROXY_KEY and IMGPROXY_SALT are set. Default: blank

Server

  • [IMGPROXY_BIND]: the address and port or Unix socket to listen to. Default: :8080
  • [IMGPROXY_NETWORK]: the network to use. Known networks are tcp, tcp4, tcp6, unix, and unixpacket. Default: tcp
  • [IMGPROXY_TIMEOUT]: the maximum duration (in seconds) for processing the response. Default: 10
  • [IMGPROXY_GRACEFUL_STOP_TIMEOUT]: the maximum duration (in seconds) to wait for ongoing requests to finish before shutting down the server. Default: twice the IMGPROXY_TIMEOUT value
  • [IMGPROXY_READ_REQUEST_TIMEOUT]: the maximum duration (in seconds) for reading the entire incoming HTTP request, including the body. Default: 10
  • [IMGPROXY_WRITE_RESPONSE_TIMEOUT]: the maximum duration (in seconds) for writing the HTTP response body. Default: 10
  • [IMGPROXY_KEEP_ALIVE_TIMEOUT]: the maximum duration (in seconds) to wait for the next request before closing the connection. When set to 0, keep-alive is disabled. Default: 10
  • [IMGPROXY_CLIENT_KEEP_ALIVE_TIMEOUT]: the maximum duration (in seconds) to wait for the next request before closing the HTTP client connection. The HTTP client is used to download source images. When set to 0, keep-alive is disabled. Default: 90
  • [IMGPROXY_DOWNLOAD_TIMEOUT]: the maximum duration (in seconds) for downloading the source image. Default: 5
  • [IMGPROXY_WORKERS]: the maximum number of images an imgproxy instance can process simultaneously without creating a queue. Default: the number of CPU cores multiplied by two :::info When running in AWS Lambda, imgproxy automatically sets IMGPROXY_WORKERS to 1 since each Lambda instance processes only one request at a time. :::
  • [IMGPROXY_REQUESTS_QUEUE_SIZE]: the maximum number of image requests that can be put in the queue. Requests that exceed this limit are rejected with 429 HTTP status. When set to 0, the requests queue is unlimited. Default: 0
  • [IMGPROXY_MAX_CLIENTS]: the maximum number of simultaneous active connections. When set to 0, connection limit is disabled. Default: 2048
  • [IMGPROXY_TTL]: a duration (in seconds) sent via the Cache-Control: max-age HTTP header. Default: 31536000 (1 year)
  • [IMGPROXY_CACHE_CONTROL_PASSTHROUGH]: when true and the source image response contains the Expires or Cache-Control headers, reuse those headers. Default: false
  • [IMGPROXY_SET_CANONICAL_HEADER]: when true and the source image has an http or https scheme, set a rel="canonical" HTTP header to the value of the source image URL. More details here. Default: false
  • [IMGPROXY_SO_REUSEPORT]: when true, enables SO_REUSEPORT socket option (currently only available on Linux and macOS);
  • [IMGPROXY_PATH_PREFIX]: the URL path prefix. Example: when set to /abc/def, the imgproxy URL will be /abc/def/%signature/%processing_options/%source_url. Default: blank
  • [IMGPROXY_USER_AGENT]: the User-Agent header that will be sent with the source image request. You can use the %current_version variable to insert the current imgproxy version. Default: imgproxy/%current_version
  • [IMGPROXY_USE_ETAG]: when set to true, enables using the ETag HTTP header for HTTP cache control. Default: false
  • [IMGPROXY_ETAG_BUSTER]: change this to change ETags for all the images. Default: blank
  • [IMGPROXY_USE_LAST_MODIFIED]: when set to true, enables using the Last-Modified HTTP header for HTTP cache control. Default: false
  • [IMGPROXY_CUSTOM_REQUEST_HEADERS]: ((pro)) list of custom headers that imgproxy will send while requesting the source image, divided by \; (can be redefined by IMGPROXY_CUSTOM_HEADERS_SEPARATOR). Example: X-MyHeader1=Lorem\;X-MyHeader2=Ipsum
  • [IMGPROXY_CUSTOM_RESPONSE_HEADERS]: ((pro)) a list of custom response headers, separated by \; (can be redefined by IMGPROXY_CUSTOM_HEADERS_SEPARATOR). Example: X-MyHeader1=Lorem\;X-MyHeader2=Ipsum
  • [IMGPROXY_CUSTOM_HEADERS_SEPARATOR]: ((pro)) a string that will be used as a custom header separator. Default: \;
  • [IMGPROXY_REQUEST_HEADERS_PASSTHROUGH]: ((pro)) a list of names of incoming request headers that should be passed through to the source image request.
  • [IMGPROXY_RESPONSE_HEADERS_PASSTHROUGH]: ((pro)) a list of names of source image response headers that should be passed through to the imgproxy response.
  • [IMGPROXY_ENABLE_DEBUG_HEADERS]: when set to true, imgproxy will add debug headers to the response. Default: false. The following headers will be added:
    • X-Origin-Content-Length: the size of the source image
    • X-Origin-Width: the width of the source image
    • X-Origin-Height: the height of the source image
    • X-Result-Width: the width of the resultant image
    • X-Result-Height: the height of the resultant image
  • [IMGPROXY_SERVER_NAME]: ((pro)) the Server header value. Default: imgproxy

Security

imgproxy protects you from so-called image bombs. Here's how you can specify the maximum image resolution which you consider reasonable:

  • [IMGPROXY_MAX_SRC_RESOLUTION]: the maximum resolution of the source image, in megapixels. Images with larger actual size will be rejected. Default: 50

    :::warning When the source image is animated, imgproxy summarizes all its frames' resolutions while checking the source image resolution unless IMGPROXY_MAX_ANIMATION_FRAME_RESOLUTION is greater than zero. :::

  • [IMGPROXY_MAX_SRC_FILE_SIZE]: the maximum size of the source image, in bytes. Images with larger file size will be rejected. When set to 0, file size check is disabled. Default: 0

imgproxy can process animated images (GIF, WebP), but since this operation is pretty memory heavy, only one frame is processed by default. You can increase the maximum animation frames that can be processed number of with the following variable:

  • [IMGPROXY_MAX_ANIMATION_FRAMES]: the maximum number of animated image frames that may be processed. Default: 1

  • [IMGPROXY_MAX_ANIMATION_FRAME_RESOLUTION]: the maximum resolution of the animated source image frame, in megapixels. Images with larger actual frame size will be rejected. When set to 0, imgproxy will test the whole animated image resolution against IMGPROXY_MAX_SRC_RESOLUTION summarising all the frames' resolutions. Default: 0

  • [IMGPROXY_MAX_RESULT_DIMENSION]: the maximum width or height the resultant image can have, in pixels. When any of the dimensions exceeds this value, imgproxy will scale the image down to fit within the specified maximum dimension. When set to 0, this check is disabled. Default: 0

  • [IMGPROXY_ALLOWED_PROCESSING_OPTIONS]: a list of processing options allowed to be used in imgproxy URLs, divided by comma. When blank, all processing options are allowed. Default: blank

    :::info If you want to allow both full and short names of a processing option, you should specify them both. For example, if you specify only resize, imgproxy will reject URLs with rs as a processing option, and vice versa. :::

    :::tip imgproxy doesn't check the processing options used in presets. This enables you to allow using a limited set of processing options directly in imgproxy URLs, while having a set of presets for the rest of them. :::

  • [IMGPROXY_ALLOWED_INFO_OPTIONS]: a list of info options allowed to be used in imgproxy URLs, divided by comma. When blank, all info options are allowed. Default: blank

    :::info If you want to allow both full and short names of an info option, you should specify them both. For example, if you specify only dominant_colors, imgproxy will reject URLs with dc as an info option, and vice versa. :::

    :::tip imgproxy doesn't check the info options used in presets. This enables you to allow using a limited set of info options directly in imgproxy URLs, while having a set of presets for the rest of them. :::

  • [IMGPROXY_MAX_CHAINED_PIPELINES]: the maximum number of chained pipelines that can be specified in the imgproxy URL. When set to 0, this check is disabled. Default: 0

    :::tip imgproxy doesn't check the number of chained pipelines used in presets :::

Requests to some image sources may go through too many redirects or enter an infinite loop. You can limit the number of allowed redirects:

  • [IMGPROXY_MAX_REDIRECTS]: the max number of redirects imgproxy can follow while requesting the source image. When set to 0, no redirects are allowed. Default: 10

You can also specify a secret key to enable authorization with the HTTP Authorization header for use in production environments:

  • [IMGPROXY_SECRET]: the authorization token. If specified, the HTTP request should contain the Authorization: Bearer %secret% header.

If you don't want to reveal your source URLs, you can encrypt them with the AES-CBC algorithm:

  • [IMGPROXY_SOURCE_URL_ENCRYPTION_KEY]: hex-encoded key used for source URL encryption. Default: blank

    :::tip Read more about source URL encryption in the encrypting the source URL guide. :::

imgproxy does not send CORS headers by default. CORS will need to be allowed by using the following variable:

  • [IMGPROXY_ALLOW_ORIGIN]: when specified, enables CORS headers with the provided origin. CORS headers are disabled by default.

You can limit allowed source URLs with the following variable:

  • [IMGPROXY_ALLOWED_SOURCES]: a whitelist of source image URL prefixes divided by comma. Wildcards can be included with * to match all characters except /. When blank, imgproxy allows all source image URLs. Example: s3://,https://*.example.com/,local://. Default: blank

    :::warning Be careful when using this config to limit source URL hosts, and always add a trailing slash after the host.

    Bad: http://example.com

    Good: http://example.com/

    If the trailing slash is absent, http://example.com@baddomain.com would be a permissable URL, however, the request would be made to baddomain.com. :::

  • [IMGPROXY_ALLOW_LOOPBACK_SOURCE_ADDRESSES]: when true, allows connecting to loopback IP addresses (127.0.0.1-127.255.255.255 and IPv6 analogues) when requesting source images. Default: false

  • [IMGPROXY_ALLOW_LINK_LOCAL_SOURCE_ADDRESSES]: when true, allows connecting to link-local multicast and unicast IP addresses (224.0.0.1-224.0.0.255, 169.254.0.1-169.254.255.255, and IPv6 analogues) when requesting source images. Default: false

  • [IMGPROXY_ALLOW_PRIVATE_SOURCE_ADDRESSES]: when true, allows connecting to private IP addresses (10.0.0.0 - 10.255.255.255, 172.16.0.0 - 172.31.255.255, 192.168.0.0 - 192.168.255.255, and IPv6 analogues) when requesting source images. Default: true

  • [IMGPROXY_PNG_UNLIMITED]: when true, disables the limit on the number of PNG chunks. Default: false

    :::warning Disabling the limit on the number of PNG chunks can lead to memory exhaustion and DoS attacks. :::

  • [IMGPROXY_SVG_UNLIMITED]: when true, disables the limit on the SVG file size (10MB). Default: false

    :::warning Disabling the limit on the SVG file size can lead to memory exhaustion and DoS attacks. :::

  • [IMGPROXY_SANITIZE_SVG]: when true, imgproxy will remove scripts from SVG images to prevent XSS attacks. Defaut: true

When using imgproxy in a development environment, it can be useful to ignore SSL verification:

  • [IMGPROXY_IGNORE_SSL_VERIFICATION]: when true, disables SSL verification, so imgproxy can be used in a development environment with self-signed SSL certificates.

Also you may want imgproxy to respond with the same error message that it writes to the log:

  • [IMGPROXY_DEVELOPMENT_ERRORS_MODE]: when true, imgproxy will respond with detailed error messages. Not recommended for production because some errors may contain stack traces.

  • [IMGPROXY_ALLOW_SECURITY_OPTIONS]: when true, allows usage of security-related processing options such as max_src_resolution, max_src_file_size, max_animation_frames, max_animation_frame_resolution, and max_result_dimension. Default: false.

    :::warning IMGPROXY_ALLOW_SECURITY_OPTIONS allows bypassing your security restrictions. Don't set it to true unless you are completely sure that an attacker can't change your imgproxy URLs. :::

Cookies

imgproxy can pass cookies in image requests. This can be activated with IMGPROXY_COOKIE_PASSTHROUGH. Unfortunately the Cookie header doesn't contain information about which URLs these cookies are applicable to, so imgproxy can only assume (or must be told).

When cookie forwarding is activated, by default, imgproxy assumes the scope of the cookies to be all URLs with the same hostname/port and request scheme as given by the headers X-Forwarded-Host, X-Forwarded-Port, X-Forwarded-Scheme or Host. To change that use IMGPROXY_COOKIE_BASE_URL.

If you want to pass cookies to any image URL regardless of the hostname, path, or scheme, you can additionally set IMGPROXY_COOKIE_PASSTHROUGH_ALL to true.

  • [IMGPROXY_COOKIE_PASSTHROUGH]: when true, incoming cookies will be passed through the image request if they are applicable for the image URL. Default: false

  • [IMGPROXY_COOKIE_BASE_URL]: when set, assume that cookies have the scope of this URL for an incoming request (instead of using request headers). If the cookies are applicable to the image URL too, they will be passed along in the image request

  • [IMGPROXY_COOKIE_PASSTHROUGH_ALL]: when true, all incoming cookies will be passed through the image request regardless of the image URL. Default: false

:::warning Cookies can contain sensitive information. Be careful when using IMGPROXY_COOKIE_PASSTHROUGH_ALL and avoid its usage unless you completely trust the servers imgproxy will send image requests to. :::

Compression

  • [IMGPROXY_QUALITY]: the default quality of the resultant image, percentage. Default: 80
  • [IMGPROXY_FORMAT_QUALITY]: default quality of the resulting image per format, separated by commas. Example: jpeg=70,avif=40,webp=60. When a value for the resulting format is not set, the IMGPROXY_QUALITY value is used. Default: webp=79,avif=63,jxl=77

Advanced JPEG compression

  • [IMGPROXY_JPEG_PROGRESSIVE]: when true, enables progressive JPEG compression. Default: false
  • [IMGPROXY_JPEG_NO_SUBSAMPLE]: ((pro)) when true, chrominance subsampling is disabled. This will improve quality at the cost of larger file size. Default: false
  • [IMGPROXY_JPEG_TRELLIS_QUANT]: ((pro)) when true, enables trellis quantisation for each 8x8 block. Reduces file size but increases compression time. Default: false
  • [IMGPROXY_JPEG_OVERSHOOT_DERINGING]: ((pro)) when true, enables overshooting of samples with extreme values. Overshooting may reduce ringing artifacts from compression, in particular in areas where black text appears on a white background. Default: false
  • [IMGPROXY_JPEG_OPTIMIZE_SCANS]: ((pro)) when true, splits the spectrum of DCT coefficients into separate scans. Reduces file size but increases compression time. Requires IMGPROXY_JPEG_PROGRESSIVE to be true. Default: false
  • [IMGPROXY_JPEG_QUANT_TABLE]: ((pro)) quantization table to use. Supported values are:
    • 0: Table from JPEG Annex K (default)
    • 1: Flat table
    • 2: Table tuned for MSSIM on Kodak image set
    • 3: Table from ImageMagick by N. Robidoux
    • 4: Table tuned for PSNR-HVS-M on Kodak image set
    • 5: Table from Relevance of Human Vision to JPEG-DCT Compression (1992)
    • 6: Table from DCTune Perceptual Optimization of Compressed Dental X-Rays (1997)
    • 7: Table from A Visual Detection Model for DCT Coefficient Quantization (1993)
    • 8: Table from An Improved Detection Model for DCT Coefficient Quantization (1993)

Advanced PNG compression

  • [IMGPROXY_PNG_INTERLACED]: when true, enables interlaced PNG compression. Default: false
  • [IMGPROXY_PNG_QUANTIZE]: when true, enables PNG quantization. libvips should be built with Quantizr or libimagequant support. Default: false
  • [IMGPROXY_PNG_QUANTIZATION_COLORS]: maximum number of quantization palette entries. Should be between 2 and 256. Default: 256

Advanced WebP compression

  • [IMGPROXY_WEBP_COMPRESSION]: ((pro)) the compression method to use. Supported values are lossy, near_lossless, and lossless. Default: lossy
  • [IMGPROXY_WEBP_SMART_SUBSAMPLE]: ((pro)) when true, enables smart subsampling. Smart subsampling increases the resulting file size and compression time but improves quality. Default: false
  • [IMGPROXY_WEBP_EFFORT]: controls the CPU effort spent improving compression. The larger the value, the slower the encoding process but the better the compression. The value should be between 1 and 6. Default: 4
  • [IMGPROXY_WEBP_PRESET]: a hint to the encoder about the type of image being compressed. Supported values are:
    • default: (default) a general-purpose preset
    • photo: a digital picture, like portrait, inner shot
    • picture: an outdoor photograph, with natural lighting
    • drawing: a hand or line drawing, with high-contrast details
    • icon: a small-sized colorful image
    • text: a text image, with large areas of uniform color

Advanced AVIF compression

  • [IMGPROXY_AVIF_SPEED]: controls the CPU effort spent improving compression. The lowest speed is at 0 and the fastest is at 9. Default: 8
  • [IMGPROXY_AVIF_SUBSAMPLE]: ((pro)) controls when chroma subsampling is used. Supported values are:
    • auto: (default) use subsampling when the image is saved with quality less than 90
    • on: always use subsampling
    • off: never use subsampling

Advanced JPEG XL compression

  • [IMGPROXY_JXL_EFFORT]: controls the CPU effort spent improving compression. The larger the value, the slower the encoding process but the better the compression. The value should be between 1 and 9. Default: 4

Autoquality

imgproxy can calculate the quality of the resulting image based on selected metric. Read more in the Autoquality guide.

:::warning Autoquality requires the image to be saved several times. Use it only when you prefer the resulting size and quality over the speed. :::

  • [IMGPROXY_AUTOQUALITY_METHOD]: ((pro)) the method of quality calculation. Default: none
  • [IMGPROXY_AUTOQUALITY_TARGET]: ((pro)) desired value of the autoquality method metric. Default: 0.02
  • [IMGPROXY_AUTOQUALITY_MIN]: ((pro)) minimal quality imgproxy can use. Default: 70
  • [IMGPROXY_AUTOQUALITY_FORMAT_MIN]: ((pro)) the minimal quality imgproxy can use per format, comma divided. Example: jpeg=70,avif=40,webp=60. When value for the resulting format is not set, IMGPROXY_AUTOQUALITY_MIN value is used. Default: avif=60
  • [IMGPROXY_AUTOQUALITY_MAX]: ((pro)) the maximum quality imgproxy can use. Default: 80
  • [IMGPROXY_AUTOQUALITY_FORMAT_MAX]: ((pro)) the maximum quality imgproxy can use per format, comma divided. Example: jpeg=70,avif=40,webp=60. When a value for the resulting format is not set, the IMGPROXY_AUTOQUALITY_MAX value is used. Default: avif=65
  • [IMGPROXY_AUTOQUALITY_ALLOWED_ERROR]: ((pro)) the allowed IMGPROXY_AUTOQUALITY_TARGET error. Applicable only to dssim and ml methods. Default: 0.001
  • [IMGPROXY_AUTOQUALITY_MAX_RESOLUTION]: ((pro)) when this value is greater then zero and the resultant resolution exceeds the value, autoquality won't be used. Default: 0
  • [IMGPROXY_AUTOQUALITY_JPEG_NET]: ((pro)) the path to the neural network for JPEG.
  • [IMGPROXY_AUTOQUALITY_WEBP_NET]: ((pro)) the path to the neural network for WebP.
  • [IMGPROXY_AUTOQUALITY_AVIF_NET]: ((pro)) the path to the neural network for AVIF.
  • [IMGPROXY_AUTOQUALITY_JXL_NET]: ((pro)) the path to the neural network for JPEG XL.

SVG processing

  • [IMGPROXY_ALWAYS_RASTERIZE_SVG]: when true, imgproxy will always rasterize SVG images unless SVG processing is not skipped. Default: false

AVIF/WebP/JPEG XL support detection

imgproxy can use the Accept HTTP header to detect if the browser supports AVIF, WebP, or JPEG XL and use it as the default format. This feature is disabled by default and can be enabled by the following options:

  • [IMGPROXY_AUTO_WEBP]: (deprecated alias: [IMGPROXY_ENABLE_WEBP_DETECTION]) enables WebP support detection. When the file extension is omitted in the imgproxy URL and browser supports WebP, imgproxy will use it as the resulting format.
  • [IMGPROXY_ENFORCE_WEBP]: enables WebP support detection and enforces WebP usage. If the browser supports WebP, it will be used as resulting format even if another extension is specified in the imgproxy URL.
  • [IMGPROXY_AUTO_AVIF]: (deprecated alias: [IMGPROXY_ENABLE_AVIF_DETECTION]) enables AVIF support detection. When the file extension is omitted in the imgproxy URL and browser supports AVIF, imgproxy will use it as the resulting format.
  • [IMGPROXY_ENFORCE_AVIF]: enables AVIF support detection and enforces AVIF usage. If the browser supports AVIF, it will be used as resulting format even if another extension is specified in the imgproxy URL.
  • [IMGPROXY_AUTO_JXL]: enables JPEG XL support detection. When the file extension is omitted in the imgproxy URL and browser supports JPEG XL, imgproxy will use it as the resulting format.
  • [IMGPROXY_ENFORCE_JXL]: enables JPEG XL support detection and enforces JPEG XL usage. If the browser supports JPEG XL, it will be used as the resulting format even if another extension is specified in the imgproxy URL.

:::info If multiple format detection/enforcement options are enabled, and the browser supports multiple of them, imgproxy will use the format with the highest priority. The priority is as follows (from the highest to the lowest): JPEG XL, AVIF, WebP :::

:::info If both the source and the requested image formats support animation and AVIF detection/enforcement is enabled, AVIF won't be used as AVIF sequence is not supported yet. :::

:::info If both the source and the requested image formats support animation and JPEG XL detection/enforcement is enabled, JPEG XL won't be used as animated JPEG XL is not widely supported by browsers yet. :::

:::tip When AVIF/WebP/JPEG XL support detection is enabled, please take care to configure your CDN or caching proxy to take the Accept HTTP header into account while caching. :::

:::warning Headers cannot be signed. This means that an attacker can bypass your CDN cache by changing the Accept HTTP headers. Keep this in mind when configuring your production caching setup. :::

Preferred formats

When the resulting image format is not explicitly specified in the imgproxy URL via the extension or the format processing option, imgproxy will choose one of the preferred formats:

  • [IMGPROXY_PREFERRED_FORMATS]: a list of preferred formats, comma divided. Default: jpeg,png,gif

imgproxy is guided by the following rules when choosing the resulting format:

  1. If the preferred formats list contains the source image format, it will be used
  2. If the resulting image is animated, the resulting image format should support animations
  3. If the resulting image contains transparency, the resulting image format should support transparency
  4. imgproxy chooses the first preferred format that meets those requirements
  5. If none of the preferred formats meet the requirements, the first preferred format is used

:::info When AVIF/WebP/JPEG XL support detection is enabled and the browser supports AVIF/WebP/JPEG XL, it may be used as the resultant format even if the preferred formats list doesn't contain it. :::

Skip processing

You can configure imgproxy to skip processing of some formats:

  • [IMGPROXY_SKIP_PROCESSING_FORMATS]: a list of formats that imgproxy shouldn't process, comma divided.

:::info Processing can only be skipped when the requested format is the same as the source format. :::

:::info Video thumbnail processing can't be skipped. :::

Best format

You can use the best value for the format option or the extension to make imgproxy pick the best format for the resultant image.

  • [IMGPROXY_BEST_FORMAT_COMPLEXITY_THRESHOLD]: ((pro)) the image complexity threshold. imgproxy will use a lossless or near-lossless encoding for images with low complexity. Default: 5.5
  • [IMGPROXY_BEST_FORMAT_MAX_RESOLUTION]: ((pro)) when greater than 0 and the image's resolution (in megapixels) is larger than the provided value, imgproxy won't try all the applicable formats and will just pick one that seems the best for the image
  • [IMGPROXY_BEST_FORMAT_BY_DEFAULT]: ((pro)) when true and the resulting image format is not specified explicitly, imgproxy will use the best format instead of the source image format
  • [IMGPROXY_BEST_FORMAT_ALLOW_SKIPS]: ((pro)) when true and the best format is used, imgproxy will skip processing of SVG and formats listed to skip processing

Check out the Best format guide to learn more.

Colorspace and HDR

  • [IMGPROXY_PRESERVE_HDR]: when true, imgproxy will preserve 16-bit images as 16-bit. When false, imgproxy will convert 16-bit images to 8-bit. Colorspace (color/grayscale) is always preserved regardless of this setting. See the Colorspace and HDR preservation guide for more details. Default: false

Client Hints support

imgproxy can use the Width and DPR HTTP headers to determine default width and DPR options using Client Hints. This feature is disabled by default and can be enabled by the following option:

  • [IMGPROXY_ENABLE_CLIENT_HINTS]: enables Client Hints support to determine default width and DPR options. Read more details here about Client Hints.

:::warning Headers cannot be signed. This means that an attacker can bypass your CDN cache by changing the Width or DPR HTTP headers. Keep this in mind when configuring your production caching setup. :::

Video thumbnails

imgproxy Pro can extract specific video frames to create thumbnails. This feature is disabled by default, but can be enabled with IMGPROXY_ENABLE_VIDEO_THUMBNAILS.

  • [IMGPROXY_ENABLE_VIDEO_THUMBNAILS]: ((pro)) when true, enables video thumbnail generation. Default: false
  • [IMGPROXY_VIDEO_THUMBNAIL_SECOND]: ((pro)) the timestamp of the frame (in seconds) that will be used for a thumbnail. Default: 1
  • [IMGPROXY_VIDEO_THUMBNAIL_KEYFRAMES]: ((pro)) when true, imgproxy will use the latest keyframe before IMGPROXY_VIDEO_THUMBNAIL_SECOND for video thumbnail generation. This makes video thumbnail generation faster yet the used frame timestamp will not be exactly equal to the requested one. Default: false
  • [IMGPROXY_VIDEO_THUMBNAIL_TILE_AUTO_KEYFRAMES]: ((pro)) when true and the step argument value of the video_thumbnail_tile processing option is greater than the interval between keyframes, imgproxy will use only keyframes. This allows to speed up video_thumbnail_tile for long steps between tiles yet keep it precise for short ones. Default: false
  • [IMGPROXY_VIDEO_THUMBNAIL_PROBE_SIZE]: ((pro)) the maximum amount of bytes used to determine the format. Lower values can decrease memory usage but can produce inaccurate data, or even lead to errors. Default: 5000000
  • [IMGPROXY_VIDEO_THUMBNAIL_MAX_ANALYZE_DURATION]: ((pro)) the maximum number of milliseconds used to get the stream info. Lower values can decrease memory usage but can produce inaccurate data, or even lead to errors. When set to 0, the heuristic is used. Default: 0

:::warning Though using IMGPROXY_VIDEO_THUMBNAIL_PROBE_SIZE and IMGPROXY_VIDEO_THUMBNAIL_MAX_ANALYZE_DURATION can lower the memory footprint of video thumbnail generation, they should be used in production only when you know what you're doing. :::

Watermark

  • [IMGPROXY_WATERMARK_DATA]: Base64-encoded image data. You can easily calculate it with base64 tmp/watermark.png | tr -d '\n'.
  • [IMGPROXY_WATERMARK_PATH]: the path to the locally stored image
  • [IMGPROXY_WATERMARK_URL]: the watermark image URL
  • [IMGPROXY_WATERMARK_PREPROCESS_URL]: ((pro)) when true, imgproxy will apply IMGPROXY_URL_REPLACEMENTS and IMGPROXY_BASE_URL to values of the watermark_url processing option.
  • [IMGPROXY_WATERMARK_OPACITY]: the watermark's base opacity
  • [IMGPROXY_WATERMARKS_CACHE_SIZE]: ((pro)) custom watermarks cache size. When set to 0, the watermark cache is disabled. 256 watermarks are cached by default.

Read more about watermarks in the Watermark guide.

Unsharp masking

imgproxy Pro can apply unsharp masking to your images.

  • [IMGPROXY_UNSHARP_MASKING_MODE]: ((pro)) controls when unsharp masking should be applied. The following modes are supported:
    • auto: (default) apply unsharp masking only when an image is downscaled and the sharpen option has not been set.
    • none: unsharp masking is not applied.
    • always: always applies unsharp masking.
  • [IMGPROXY_UNSHARP_MASKING_WEIGHT]: ((pro)) a floating-point number that defines how neighboring pixels will affect the current pixel. The greater the value, the sharper the image. This value should be greater than zero. Default: 1
  • [IMGPROXY_UNSHARP_MASKING_DIVIDER]: ((pro)) a floating-point number that defines unsharp masking strength. The lesser the value, the sharper the image. This value be greater than zero. Default: 24

Smart crop

  • [IMGPROXY_SMART_CROP_ADVANCED]: ((pro)) when true, enables usage of the advanced smart crop method. Advanced smart crop may take more time than regular one, yet it produces better results.
  • [IMGPROXY_SMART_CROP_ADVANCED_MODE]: ((pro)) the mode of the advanced smart crop method. Supported values are:
    • max_score_area: (default) in this mode, imgproxy builds a featres map and selects the area with the highest sum of feature scores.
    • center_of_mass: in this mode, imgproxy calculates the center of mass of the features map and selects the area around it.
  • [IMGPROXY_SMART_CROP_FACE_DETECTION]: ((pro)) when true, adds an additional fast face detection step to smart crop.

Object detection

imgproxy can detect objects on the image and use them to perform smart cropping, to blur the detections, or to draw the detections.

  • [IMGPROXY_OBJECT_DETECTION_NET]: ((pro)) a path to the neural network model in ONNX format. Default: blank
  • [IMGPROXY_OBJECT_DETECTION_NET_TYPE]: ((pro)) the type of the neural network model. Default: yolox
  • [IMGPROXY_OBJECT_DETECTION_CLASSES]: ((pro)) the path to the text file with the classes names, one per line. Default: blank
  • [IMGPROXY_OBJECT_DETECTION_NET_SIZE]: ((pro)) the size of the neural network input. The width and the heights of the inputs should be the same, so this config value should be a single number. Default: 416
  • [IMGPROXY_OBJECT_DETECTION_CONFIDENCE_THRESHOLD]: ((pro)) detections with confidences below this value will be discarded. Default: 0.2
  • [IMGPROXY_OBJECT_DETECTION_NMS_THRESHOLD]: ((pro)) non-max supression threshold. Don't change this if you don't know what you're doing. Default: 0.4
  • [IMGPROXY_OBJECT_DETECTION_SWAP_RB]: ((pro)) when set to true, imgproxy will swap the R and B channels in the input image. Some models are trained on BGR images and perform incorrectly with RGB inputs. This option allows you to fix this issue. Default: false
  • [IMGPROXY_OBJECT_DETECTION_FALLBACK_TO_SMART_CROP]: ((pro)) defines imgproxy's behavior when object-oriented crop gravity is used but no objects are detected. When set to true, imgproxy will fallback to smart crop. When set to false, imgproxy will fallback to the center gravity. Default: true
  • [IMGPROXY_OBJECT_DETECTION_GRAVITY_MODE]: ((pro)) defines how imgproxy should use object-oriented crop gravity. Supported values are:
    • max_score_area: (default) in this mode, imgproxy will select the area that covers the most detected objects, respecting their weights.
    • 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.

Read the Object Detection guide for more info.

Object classification

imgproxy can classify detected objects on the image and provide detailed information about what the objects are.

  • [IMGPROXY_OBJECT_CLASSIFY_NET]: ((pro)) a path to the classification neural network model in ONNX format. Default: blank
  • [IMGPROXY_OBJECT_CLASSIFY_CLASSES]: ((pro)) the path to the text file with the class names, one per line. Default: blank
  • [IMGPROXY_OBJECT_CLASSIFY_NET_SIZE]: ((pro)) the size of the neural network input. The width and the heights of the inputs should be the same, so this config value should be a single number. Default: 224
  • [IMGPROXY_OBJECT_CLASSIFY_THRESHOLD]: ((pro)) classifications with confidence below this value will be discarded. Default: 0.5
  • [IMGPROXY_OBJECT_CLASSIFY_NORMALIZATION]: ((pro)) the normalization type to apply to the input image. Possible values are:
    • none: (default) no normalization
    • half: normalize to [-0.5, 0.5] range
    • full: normalize to [-1, 1] range
    • imagenet: normalize using ImageNet mean and standard deviation
  • [IMGPROXY_OBJECT_CLASSIFY_LAYOUT]: ((pro)) the data layout of the neural network input. Possible values are:
    • nchw: (default) channels first
    • nhwc: channels last

Read the Object Classification guide for more info.

Cache

imgproxy can cache processed images in various storage backends to improve performance and reduce processing overhead.

  • [IMGPROXY_CACHE_USE]: ((pro)) the cache storage adapter to use. Can be filesystem, s3, gcs, abs (Azure Blob Storage), or swift. When blank, the cache is disabled. Default: blank
  • [IMGPROXY_CACHE_PATH_PREFIX]: ((pro)) 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]: ((pro)) the bucket name for cloud storage adapters (S3, GCS, ABS, Swift). When using filesystem adapter, this can be used as an additional path component. Default: blank
  • [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

Cache storage: Local filesystem {#cache-storage-local-filesystem}

imgproxy can store cached images on the local filesystem. To use filesystem cache, set IMGPROXY_CACHE_USE to filesystem:

  • [IMGPROXY_CACHE_LOCAL_FILESYSTEM_ROOT]: ((pro)) the root directory for filesystem cache. Default: blank

Cache storage: Amazon S3 {#cache-storage-amazon-s3}

imgproxy can store cached images in Amazon S3 buckets or S3-compatible storage. To use S3 cache, set IMGPROXY_CACHE_USE to s3:

  • [IMGPROXY_CACHE_S3_REGION]: ((pro)) the S3 region for the cache bucket
  • [IMGPROXY_CACHE_S3_ENDPOINT]: ((pro)) a custom S3 endpoint for the cache. Useful for S3-compatible services like MinIO, Cloudflare R2, DigitalOcean Spaces, etc. Default: blank
  • [IMGPROXY_CACHE_S3_ENDPOINT_USE_PATH_STYLE]: ((pro)) controls how the S3 bucket endpoint is constructed. When true, the endpoint will be constructed using the path style (https://your-endpoint.com/%bucket). When false, the endpoint will be constructed using the virtual host style (https://%bucket.your-endpoint.com). Default: true
  • [IMGPROXY_CACHE_S3_USE_DECRYPTION_CLIENT]: ((pro)) when true, enables client-side decryption for cached objects. Default: false
  • [IMGPROXY_CACHE_S3_ASSUME_ROLE_ARN]: ((pro)) the ARN of an IAM role to assume for cache access
  • [IMGPROXY_CACHE_S3_ASSUME_ROLE_EXTERNAL_ID]: ((pro)) the external ID required to assume the IAM role for cache access

:::info Credentials for S3 cache can be provided using the same methods as for S3 image sources: IAM roles, AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables, or a shared credentials file. :::

Cache storage: Google Cloud Storage {#cache-storage-google-cloud-storage}

imgproxy can store cached images in Google Cloud Storage buckets. To use GCS cache, set IMGPROXY_CACHE_USE to gcs:

  • [IMGPROXY_CACHE_GCS_KEY]: ((pro)) the Google Cloud JSON key for cache access. When running inside Google Cloud infrastructure, imgproxy will try to use the default service account credentials if this is not set. Default: blank
  • [IMGPROXY_CACHE_GCS_ENDPOINT]: ((pro)) a custom Google Cloud Storage endpoint for cache. Default: blank

Cache storage: Azure Blob Storage {#cache-storage-azure-blob-storage}

imgproxy can store cached images in Azure Blob Storage containers. To use Azure cache, set IMGPROXY_CACHE_USE to abs:

  • [IMGPROXY_CACHE_ABS_NAME]: ((pro)) the Azure account name for cache storage. Default: blank
  • [IMGPROXY_CACHE_ABS_KEY]: ((pro)) the Azure account key for cache storage. Default: blank
  • [IMGPROXY_CACHE_ABS_ENDPOINT]: ((pro)) a custom Azure Blob Storage endpoint for cache. Default: blank

:::info Azure cache also supports authentication via Managed Identity or Service Principal using the same AZURE_CLIENT_ID, AZURE_TENANT_ID, and related environment variables as Azure Blob Storage image sources. :::

Cache storage: OpenStack Swift {#cache-storage-openstack-swift}

imgproxy can store cached images in OpenStack Object Storage (Swift). To use Swift cache, set IMGPROXY_CACHE_USE to swift:

  • [IMGPROXY_CACHE_SWIFT_USERNAME]: ((pro)) the username for Swift API access for cache. Default: blank
  • [IMGPROXY_CACHE_SWIFT_API_KEY]: ((pro)) the API key for Swift API access for cache. Default: blank
  • [IMGPROXY_CACHE_SWIFT_AUTH_URL]: ((pro)) the Swift Auth URL for cache. Default: blank
  • [IMGPROXY_CACHE_SWIFT_AUTH_VERSION]: ((pro)) the Swift auth version for cache. Set to 1, 2 or 3 or leave at 0 for autodetect. Default: 0
  • [IMGPROXY_CACHE_SWIFT_TENANT]: ((pro)) the tenant name for cache (optional, v2 auth only). Default: blank
  • [IMGPROXY_CACHE_SWIFT_DOMAIN]: ((pro)) the Swift domain name for cache (optional, v3 auth only). Default: blank
  • [IMGPROXY_CACHE_SWIFT_TIMEOUT_SECONDS]: ((pro)) the data channel timeout in seconds for cache operations. Default: 60
  • [IMGPROXY_CACHE_SWIFT_CONNECT_TIMEOUT_SECONDS]: ((pro)) the connect channel timeout in seconds for cache operations. Default: 10

Read the Cache guide for more info.

Fallback image

You can set up a fallback image that will be used in case imgproxy is unable to fetch the requested one. Use one of the following variables:

  • [IMGPROXY_FALLBACK_IMAGE_DATA]: Base64-encoded image data. You can easily calculate it with base64 tmp/fallback.png | tr -d '\n'.
  • [IMGPROXY_FALLBACK_IMAGE_PATH]: the path to the locally stored image
  • [IMGPROXY_FALLBACK_IMAGE_URL]: the fallback image URL
  • [IMGPROXY_FALLBACK_IMAGE_PREPROCESS_URL]: ((pro)) when true, imgproxy will apply IMGPROXY_URL_REPLACEMENTS and IMGPROXY_BASE_URL to values of the fallback_image_url processing option.
  • [IMGPROXY_FALLBACK_IMAGE_HTTP_CODE]: the HTTP code for the fallback image response. When set to zero, imgproxy will respond with the usual HTTP code. Default: 200
  • [IMGPROXY_FALLBACK_IMAGE_TTL]: a duration (in seconds) sent via the Cache-Control: max-age HTTP header when a fallback image was used. When blank or 0, the value from IMGPROXY_TTL is used.
  • [IMGPROXY_FALLBACK_IMAGES_CACHE_SIZE]: ((pro)) the size of custom fallback images cache. When set to 0, the fallback image cache is disabled. 256 fallback images are cached by default.

Presets

Read more about imgproxy presets in the Presets guide.

There are two ways to define presets:

Using an environment variable

  • [IMGPROXY_PRESETS]: a set of processing preset definitions, comma divided. Example: default=resizing_type:fill/enlarge:1,sharp=sharpen:0.7,blurry=blur:2. Default: blank

  • [IMGPROXY_INFO_PRESETS]: ((pro)) a set of info preset definitions, comma divided. Example: default=xmp:0/blurhash:4:3. Default: blank

  • [IMGPROXY_PRESETS_SEPARATOR]: a string that will be used as a presets' separator. Default: ,

  • [IMGPROXY_PRESETS_PATH]: the path to the file with processing preset definitions. Default: blank

    The file should contain processing preset definitions, one per line. Lines starting with # are treated as comments. Example:

    default=resizing_type:fill/enlarge:1

# Sharpen the image to make it look better
sharp=sharpen:0.7

# Blur the image to hide details
blurry=blur:2

  • [IMGPROXY_INFO_PRESETS_PATH]: ((pro)) the path to the file with info preset definitions. Default: blank

    The file should contain info preset definitions, one per line. Lines starting with # are treated as comments. Example:

    default=xmp:0/blurhash:4:3

# Detect objects on the image
with_objects=detect_objects:1

Using only presets

imgproxy can be switched into "presets-only mode". In this mode, imgproxy accepts only preset option arguments as processing options. Example: http://imgproxy.example.com/unsafe/thumbnail:blurry:watermarked/plain/http://example.com/images/curiosity.jpg@png

  • [IMGPROXY_ONLY_PRESETS]: when true, enables presets-only mode. Default: false
  • [IMGPROXY_INFO_ONLY_PRESETS]: when true, enables presets-only mode for the info endpoint. Default: IMGPROXY_ONLY_PRESETS value

Image sources

  • [IMGPROXY_SOURCE_URL_QUERY_SEPARATOR]: a string that will be used as a separator between non-HTTP(S) source URLs' paths and their query strings. When blank, imgproxy won't extract query string from non-HTTP(S) source URLs. Default: ?

:::tip If filenames in your S3/Google Cloud Storage/local filesystem/etc may contain ?, you may want to set IMGPROXY_SOURCE_URL_QUERY_SEPARATOR to another string that is not used in filenames or set it to blank to disable query string extraction. :::

Local files {#serving-local-files}

imgproxy can serve your local images, but this feature is disabled by default. To enable it, specify your local filesystem root:

  • [IMGPROXY_LOCAL_FILESYSTEM_ROOT]: the root of the local filesystem. Keep this empty to disable local file serving.

Check out the Serving local files guide to learn more.

Amazon S3 {#serving-files-from-amazon-s3}

imgproxy can process files from Amazon S3 buckets, but this feature is disabled by default. To enable it, set IMGPROXY_USE_S3 to true:

  • [IMGPROXY_USE_S3]: when true, enables image fetching from Amazon S3 buckets. Default: false
  • [IMGPROXY_S3_REGION]: an S3 buckets region
  • [IMGPROXY_S3_ENDPOINT]: a custom S3 endpoint to being used by imgproxy
  • [IMGPROXY_S3_ENDPOINT_USE_PATH_STYLE]: controls how the S3 bucket endpoint is constructed. When true, the endpoint will be constructed using the path style (https://your-endpoint.com/%bucket). When false, the endpoint will be constructed using the virtual host style (https://%bucket.your-endpoint.com). Default: true
  • [IMGPROXY_S3_USE_DECRYPTION_CLIENT]: when true, enables client-side decryption. Default: false
  • [IMGPROXY_S3_ASSUME_ROLE_ARN]: a custom role to assume
  • [IMGPROXY_S3_ASSUME_ROLE_EXTERNAL_ID]: the external ID required to assume a custom role
  • [IMGPROXY_S3_ALLOWED_BUCKETS]: a comma-separated list of S3 bucket names that imgproxy is allowed to access. When set, imgproxy will only process images from these buckets. Default: blank (all buckets allowed)
  • [IMGPROXY_S3_DENIED_BUCKETS]: a comma-separated list of S3 bucket names that imgproxy is not allowed to access. When set, imgproxy will reject requests for images from these buckets. Default: blank

Check out the Serving files from S3 guide to learn more.

Google Cloud Storage {#serving-files-from-google-cloud-storage}

imgproxy can process files from Google Cloud Storage buckets, but this feature is disabled by default. To enable it, set the value of IMGPROXY_USE_GCS to true:

  • [IMGPROXY_USE_GCS]: when true, enables image fetching from Google Cloud Storage buckets. Default: false
  • [IMGPROXY_GCS_KEY]: the Google Cloud JSON key. Default: blank
  • [IMGPROXY_GCS_ENDPOINT]: a custom Google Cloud Storage endpoint to being used by imgproxy
  • [IMGPROXY_GCS_ALLOWED_BUCKETS]: a comma-separated list of GCS bucket names that imgproxy is allowed to access. When set, imgproxy will only process images from these buckets. Default: blank (all buckets allowed)
  • [IMGPROXY_GCS_DENIED_BUCKETS]: a comma-separated list of GCS bucket names that imgproxy is not allowed to access. When set, imgproxy will reject requests for images from these buckets. Default: blank

Check out the Serving files from Google Cloud Storage guide to learn more.

Azure Blob Storage {#serving-files-from-azure-blob-storage}

imgproxy can process files from Azure Blob Storage containers, but this feature is disabled by default. To enable it, set IMGPROXY_USE_ABS to true:

  • [IMGPROXY_USE_ABS]: when true, enables image fetching from Azure Blob Storage containers. Default: false
  • [IMGPROXY_ABS_NAME]: the Azure account name. Default: blank
  • [IMGPROXY_ABS_KEY]: the Azure account key. Default: blank
  • [IMGPROXY_ABS_ENDPOINT]: the custom Azure Blob Storage endpoint to be used by imgproxy. Default: blank
  • [IMGPROXY_ABS_ALLOWED_BUCKETS]: a comma-separated list of Azure Blob Storage container names that imgproxy is allowed to access. When set, imgproxy will only process images from these containers. Default: blank (all containers allowed)
  • [IMGPROXY_ABS_DENIED_BUCKETS]: a comma-separated list of Azure Blob Storage container names that imgproxy is not allowed to access. When set, imgproxy will reject requests for images from these containers. Default: blank

Check out the Serving files from Azure Blob Storage guide to learn more.

OpenStack Object Storage ("Swift") {#serving-files-from-openstack-object-storage-swift}

imgproxy can process files from OpenStack Object Storage, but this feature is disabled by default. To enable it, set IMGPROXY_USE_SWIFT to true.

  • [IMGPROXY_USE_SWIFT]: when true, enables image fetching from OpenStack Swift Object Storage. Default: false
  • [IMGPROXY_SWIFT_USERNAME]: the username for Swift API access. Default: blank
  • [IMGPROXY_SWIFT_API_KEY]: the API key for Swift API access. Default: blank
  • [IMGPROXY_SWIFT_AUTH_URL]: the Swift Auth URL. Default: blank
  • [IMGPROXY_SWIFT_AUTH_VERSION]: the Swift auth version, set to 1, 2 or 3 or leave at 0 for autodetect.
  • [IMGPROXY_SWIFT_TENANT]: the tenant name (optional, v2 auth only). Default: blank
  • [IMGPROXY_SWIFT_DOMAIN]: the Swift domain name (optional, v3 auth only): Default: blank
  • [IMGRPOXY_SWIFT_TIMEOUT_SECONDS]: the data channel timeout in seconds. Default: 60
  • [IMGRPOXY_SWIFT_CONNECT_TIMEOUT_SECONDS]: the connect channel timeout in seconds. Default: 10
  • [IMGPROXY_SWIFT_ALLOWED_BUCKETS]: a comma-separated list of Swift container names that imgproxy is allowed to access. When set, imgproxy will only process images from these containers. Default: blank (all containers allowed)
  • [IMGPROXY_SWIFT_DENIED_BUCKETS]: a comma-separated list of Swift container names that imgproxy is not allowed to access. When set, imgproxy will reject requests for images from these containers. Default: blank

Check out the Serving files from OpenStack Object Storage guide to learn more.

Source image URLs

  • [IMGPROXY_BASE_URL]: a base URL prefix that will be added to each source image URL. For example, if the base URL is http://example.com/images and /path/to/image.png is requested, imgproxy will download the source image from http://example.com/images/path/to/image.png. If the image URL already contains the prefix, it won't be added. Default: blank

  • [IMGPROXY_URL_REPLACEMENTS]: a list of pattern=replacement pairs, semicolon (;) divided. imgproxy will replace source URL prefixes matching the pattern with the corresponding replacement. Wildcards can be included in patterns with * to match all characters except /. ${N} in replacement strings will be replaced with wildcard values, where N is the number of the wildcard. Examples:

    • mys3://=s3://my_bucket/images/ will replace mys3://image01.jpg with s3://my_bucket/images/image01.jpg
    • mys3://*/=s3://my_bucket/${1}/images will replace mys3://items/image01.jpg with s3://my_bucket/items/images/image01.jpg

:::info Replacements defined in IMGPROXY_URL_REPLACEMENTS are applied before IMGPROXY_BASE_URL is added. :::

  • [IMGPROXY_BASE64_URL_INCLUDES_FILENAME]: when true and the source image URL is Base64-encoded or encrypted, imgproxy will treat the part after the last slash (/) as an SEO-friendly filename and will discard it when decoding the URL. Default: false

:::tip For example, if you have IMGPROXY_BASE64_URL_INCLUDES_FILENAME enabled and want to add a puppy.jpg filename to your imgproxy URL for SEO reasons, the URL will look like this:

https://my-imgproxy.dev/.../aHR0cDovL2V4YW1wbGUuY29tL3B1cHB5LmpwZw/puppy.jpg

imgproxy will treat puppy.jpg as an SEO-friendly filename and will use aHR0cDovL2V4YW1wbGUuY29tL3B1cHB5LmpwZw as a Base64-encoded source URL. :::

Metrics

New Relic {#new-relic-metrics}

imgproxy can send its metrics to New Relic. Specify your New Relic license key to activate this feature:

  • [IMGPROXY_NEW_RELIC_KEY]: the New Relic license key
  • [IMGPROXY_NEW_RELIC_APP_NAME]: a New Relic application name. Default: imgproxy
  • [IMGPROXY_NEW_RELIC_LABELS]: the list of New Relic labels, semicolon divided. Example: label1=value1;label2=value2. Default: blank
  • [IMGPROXY_NEW_RELIC_PROPAGATE_EXTERNAL]: when true, imgproxy will propagate New Relic tracing headers to external requests such as image downloads. Default: false

Check out the New Relic guide to learn more.

Prometheus {#prometheus-metrics}

imgproxy can collect its metrics for Prometheus. Specify a binding for Prometheus metrics server to activate this feature:

  • [IMGPROXY_PROMETHEUS_BIND]: Prometheus metrics server binding. Can't be the same as IMGPROXY_BIND. Default: blank
  • [IMGPROXY_PROMETHEUS_NAMESPACE]: Namespace (prefix) for imgproxy metrics. Default: blank

Check out the Prometheus guide to learn more.

Datadog {#datadog-metrics}

imgproxy can send its metrics to Datadog:

  • [IMGPROXY_DATADOG_ENABLE]: when true, enables sending metrics to Datadog. Default: false
  • [IMGPROXY_DATADOG_ENABLE_ADDITIONAL_METRICS]: when true, enables sending the additional metrics to Datadog. Default: false
  • [IMGPROXY_DATADOG_PROPAGATE_EXTERNAL]: when true, imgproxy will propagate Datadog tracing headers to external requests such as image downloads. Default: false

:::warning Since the additional metrics are treated by Datadog as custom, Datadog can additionally bill you for their usage. Please, check out Datadog's Custom Metrics Billing page for additional details. :::

Check out the Datadog guide to learn more.

OpenTelemetry {#opentelemetry-metrics}

imgproxy can send request traces to an OpenTelemetry collector:

  • [IMGPROXY_OPEN_TELEMETRY_ENABLE]: when true, enables sending request traces to OpenTelemetry collector. Default: false
  • [IMGPROXY_OPEN_TELEMETRY_ENABLE_METRICS]: when true, imgproxy will send metrics over OpenTelemetry Metrics API. Default: false
  • [IMGPROXY_OPEN_TELEMETRY_ENABLE_LOGS]: when true, imgproxy will send logs to OpenTelemetry collector. Default: false
  • [IMGPROXY_OPEN_TELEMETRY_SERVER_CERT]: OpenTelemetry collector TLS certificate, PEM-encoded (you can replace line breaks with \n). Default: blank
  • [IMGPROXY_OPEN_TELEMETRY_CLIENT_CERT]: OpenTelemetry client TLS certificate, PEM-encoded (you can replace line breaks with \n). Default: blank
  • [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

Check out the OpenTelemetry guide to learn more.

Amazon CloudWatch metrics {#amazon-cloudwatch-metrics}

imgproxy can send its metrics to Amazon CloudWatch. Specify a desired ServiceName dimesion value to activate this feature:

  • [IMGPROXY_CLOUD_WATCH_SERVICE_NAME]: the value of the ServiceName dimension which will be used in the metrics. Default: blank
  • [IMGPROXY_CLOUD_WATCH_NAMESPACE]: the CloudWatch namespace for the metrics
  • [IMGPROXY_CLOUD_WATCH_REGION]: the code of the AWS region to which the metrics should be sent

Check out the CloudWatch guide to learn more.

Error reporting

imgproxy can report occurred errors to Bugsnag, Honeybadger and Sentry:

  • [IMGPROXY_REPORT_DOWNLOADING_ERRORS]: when true, imgproxy will report downloading errors. Default: true
  • [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. Default: false

Bugsnag

  • [IMGPROXY_BUGSNAG_KEY]: Bugsnag API key. When provided, enables error reporting to Bugsnag.
  • [IMGPROXY_BUGSNAG_STAGE]: the Bugsnag stage to report to. Default: production

Honeybadger

  • [IMGPROXY_HONEYBADGER_KEY]: the Honeybadger API key. When provided, enables error reporting to Honeybadger.
  • [IMGPROXY_HONEYBADGER_ENV]: the Honeybadger env to report to. Default: production

Sentry

  • [IMGPROXY_SENTRY_DSN]: Sentry project DSN. When provided, enables error reporting to Sentry.
  • [IMGPROXY_SENTRY_ENVIRONMENT]: the Sentry environment to report to. Default: production
  • [IMGPROXY_SENTRY_RELEASE]: the Sentry release to report to. Default: imgproxy@{imgproxy version}

Airbrake

  • [IMGPROXY_AIRBRAKE_PROJECT_ID]: an Airbrake project id
  • [IMGPROXY_AIRBRAKE_PROJECT_KEY]: an Airbrake project key
  • [IMGPROXY_AIRBRAKE_ENVIRONMENT]: the Airbrake environment to report to. Default: production

Log

  • [IMGPROXY_LOG_FORMAT]: the log format. The following formats are supported:
    • pretty: (default) colored human-readable format
    • structured: machine-readable format
    • json: JSON format
    • gcp: Google Cloud Logging agent compliant format
  • [IMGPROXY_LOG_LEVEL]: the log level. The following levels are supported error, warn, info and debug. Default: info

imgproxy can send logs to syslog, but this feature is disabled by default. To enable it, set IMGPROXY_SYSLOG_ENABLE to true:

  • [IMGPROXY_SYSLOG_ENABLE]: when true, enables sending logs to syslog.
  • [IMGPROXY_SYSLOG_LEVEL]: the maximum log level to send to syslog. Known levels are: crit, error, warning and info. Default: info
  • [IMGPROXY_SYSLOG_NETWORK]: the network that will be used to connect to syslog. When blank, the local syslog server will be used. Known networks are tcp, tcp4, tcp6, udp, udp4, udp6, ip, ip4, ip6, unix, unixgram and unixpacket. Default: blank
  • [IMGPROXY_SYSLOG_ADDRESS]: the address of the syslog service. Not used if IMGPROXY_SYSLOG_NETWORK is blank. Default: blank
  • [IMGPROXY_SYSLOG_TAG]: the specific syslog tag. Default: imgproxy

:::info imgproxy always uses structured log format for syslog. :::

Licensing

  • [IMGPROXY_LICENSE_KEY]: ((pro)) the imgproxy Pro license key. When not provided, imgproxy Pro will run in development mode with a limit of 100 requests per minute. Default: blank
  • [IMGPROXY_LICENSE_DEVELOPMENT_MODE]: ((pro)) when true, enables development mode even if IMGPROXY_LICENSE_KEY is provided. In development mode, imgproxy Pro will run with a limit of 100 requests per minute but won't meter the license usage. Default: false

:::info If you bought imgproxyPro in a cloud marketplace (like AWS Marketplace), you don't need to set IMGPROXY_LICENSE_KEY. You can still use IMGPROXY_LICENSE_DEVELOPMENT_MODE to enable development mode for local testing. :::

Memory usage tweaks

:::danger We highly recommended reading the Memory usage tweaks guide before changing these settings. :::

  • [IMGPROXY_DOWNLOAD_BUFFER_SIZE]: the initial size (in bytes) of a single download buffer. When set to zero, initializes empty download buffers. Default: 0
  • [IMGPROXY_FREE_MEMORY_INTERVAL]: the interval (in seconds) at which unused memory will be returned to the OS. Default: 10
  • [IMGPROXY_BUFFER_POOL_CALIBRATION_THRESHOLD]: the number of buffers that should be returned to a pool before calibration. Default: 1024
  • [IMGPROXY_MALLOC]: (Docker only) malloc implementation to use. The following implementations are supported:

Miscellaneous

  • [IMGPROXY_ARGUMENTS_SEPARATOR]: a string that will be used as a processing/info options arguments' separator. Default: :
  • [IMGPROXY_USE_LINEAR_COLORSPACE]: when true, imgproxy will process images in linear colorspace. This will slow down processing. Note that images won't be fully processed in linear colorspace while shrink-on-load is enabled (see below).
  • [IMGPROXY_DISABLE_SHRINK_ON_LOAD]: when true, disables shrink-on-load for JPEGs and WebP files. Allows processing the entire image in linear colorspace but dramatically slows down resizing and increases memory usage when working with large images.
  • [IMGPROXY_PDF_NO_BACKGROUND]: ((pro)) when true, imgproxy will not add a white background to the PDF pages. Default: false
  • [IMGPROXY_STRIP_METADATA]: when true, imgproxy will strip the output images' metadata (EXIF, IPTC, etc.). Default: true
  • [IMGPROXY_KEEP_COPYRIGHT]: when true, imgproxy will not remove copyright info while stripping metadata. Default: true
  • [IMGPROXY_STRIP_METADATA_DPI]: ((pro)) the DPI metadata value that should be set for the image when its metadata is stripped. Default: 72.0
  • [IMGPROXY_STRIP_COLOR_PROFILE]: when true, imgproxy will transform the embedded color profile (ICC) to sRGB and remove it from the image. Otherwise, imgproxy will try to keep it as is. Default: true
  • [IMGPROXY_COLOR_PROFILES_DIR]: ((pro)) the path to the directory containing color profiles that can be used with the color_profile processing option. Default: /usr/share/color/icc
  • [IMGPROXY_AUTO_ROTATE]: when true, imgproxy will automatically rotate images based on the EXIF Orientation parameter (if available in the image meta data). The orientation tag will be removed from the image in all cases. Default: true
  • [IMGPROXY_ENFORCE_THUMBNAIL]: when true and the source image has an embedded thumbnail, imgproxy will always use the embedded thumbnail instead of the main image. Currently, only thumbnails embedded in heic and avif are supported. Default: false
  • [IMGPROXY_RETURN_ATTACHMENT]: when true, response header Content-Disposition will include attachment. Default: false
  • [IMGPROXY_HEALTH_CHECK_MESSAGE]: ((pro)) the content of the health check response. Default: imgproxy is running
  • [IMGPROXY_HEALTH_CHECK_PATH]: an additional path of the health check. Default: blank
  • [IMGPROXY_FAIL_ON_DEPRECATION]: when true, imgproxy will exit with a fatal error if a deprecated config option is used. Default: false