Skip to content

image_formats_support.mdx

Latest commit

 

History

History
200 lines (151 loc) · 7.49 KB

image_formats_support.mdx

File metadata and controls

200 lines (151 loc) · 7.49 KB
description Learn about image formats supported by imgproxy

Image formats support

At the moment, imgproxy supports only the most popular image formats:

Format Extension Source Result
PNG png ✅ ✅
JPEG jpg ✅ ✅
JPEG XL jxl ✅ See notes
WebP webp ✅ ✅
AVIF avif ✅ ✅
GIF gif ✅ ✅
ICO ico ✅ ✅
SVG svg ✅ See notes
HEIC heic ✅ ✅
BMP bmp ✅ ✅
TIFF tiff ✅ ✅
PDF ((pro)) pdf ✅ See notes
PSD ((pro)) psd See notes ❌
RAW ((pro)) See notes ❌
MP4 (h264) ((pro)) mp4 See notes ✅
Other video formats ((pro)) See notes ❌

JPEG XL support {#jxl-support}

imgproxy supports JPEG XL as a source format without limitations.

When JPEG XL is used as a result format, animations are not supported because animated JPEG XL is not yet supported by browsers.

SVG support

imgproxy supports SVG sources without limitations, but SVG results are not supported when the source image is not SVG.

When the source image is SVG and an SVG result is requested, imgproxy returns the source image without modifications.

Animated images support

Since the processing of animated images is a pretty heavy process, only one frame is processed by default. You can increase the maximum of animation frames to process with the following variable:

  • IMGPROXY_MAX_ANIMATION_FRAMES: the maximum of animated image frames to be processed. Default: 1.

:::info imgproxy summarizes all frames resolutions while the checking source image resolution. :::

PDF support ((pro)) {#pdf-support}

imgproxy supports PDF both as a source and result format.

When PDF is used as a source, imgproxy renders the specified pages as raster images.

When PDF is used as a result format, imgproxy renders the image as a JPEG image and embeds it into a single-page PDF document.

PSD support ((pro)) {#psd-support}

PSD (Photoshop Document) and PSB (Photoshop Big) files are supported as source images, but there are some limitations:

PSD/PSB files should be saved with Photoshop's "Maximize Compatibility" option enabled, which is enabled by default. If this option is disabled, imgproxy won't return an error but will render the PSD/PSB file as a solid white image.

We tested imgproxy with all variants of PSD/PSB files that we could find or produce with Adobe Photoshop 2025. If you encounter any PSD/PSB file that imgproxy can't process, please let us know.

:::warning We couldn't find any PSD/PSB files with their image data compressed with ZIP, so imgproxy renders them as solid white images. If you had such files, we would very much appreciate it if you could share them with us. :::

RAW support ((pro)) {#raw-support}

RAW image formats from digital cameras are supported as source images only (read-only). RAW files are decoded and converted to standard image formats during processing.

imgproxy uses libraw to process RAW files. For a complete list of supported camera models and RAW formats, see the libraw supported cameras list.

RAW format detection ((pro)) {#raw-detect}

imgproxy detects RAW formats using the following process:

  1. Standard format detection: First, imgproxy attempts to detect if the file is in a known non-RAW format (such as JPEG, PNG, WebP, etc.) by using magic bytes signatures.
  2. MIME type checking: If no standard format is detected through magic bytes, imgproxy checks whether the MIME type matches any of the known RAW MIME types.
  3. Extension checking: If the MIME type does not match, imgproxy checks if the file extension matches any of the known RAW extensions.
Supported RAW MIME types 
image/x-hasselblad-3fr
image/x-adobe-dng
image/x-sony-arw
image/x-phaseone-cap
image/x-canon-cr2
image/x-canon-cr3
image/x-canon-crw
image/x-kodak-dcr
image/x-epson-erf
image/x-hasselblad-fff
image/x-gopro-gpr
image/x-phaseone-iiq
image/x-kodak-k25
image/x-kodak-kdc
image/x-mamiya-mef
image/x-leaf-mos
image/x-minolta-mrw
image/x-nikon-nef
image/x-nikon-nrw
image/x-olympus-orf
image/x-sony-ori
image/x-pentax-pef
image/x-apple-proraw
image/x-fuji-raf
image/x-raw
image/x-panasonic-rw2
image/x-leica-rwl
image/x-sony-sr2
image/x-sony-srf
image/x-samsung-srw
image/x-sigma-x3f
Supported RAW file extensions 
.3fr
.adng
.arw
.cap
.cr2
.cr3
.crw
.data
.dcr
.dng
.eip
.erf
.fff
.gpr
.iiq
.k25
.kdc
.mef
.moc
.mos
.mdc
.mrw
.nef
.nrw
.orf
.ori
.pef
.ppm
.proraw
.raf
.raw
.rw2
.rwl
.sr2
.srf
.srw
.x3f

Converting animated images to MP4 ((pro)) {#converting-animated-images-to-mp4}

Animated image results can be converted to MP4 by specifying the mp4 extension.

Since MP4 requires use of a <video> tag instead of <img>, automatic conversion to MP4 is not provided.

Video thumbnails ((pro)) {#video-thumbnails}

If you provide a video as a source, imgproxy takes a specific frame to create a thumbnail. To do this, imgproxy downloads only the amount of data required to reach the needed frame.

Since this still requires more data to be downloaded, video thumbnail generation is disabled by default and should be enabled with IMGPROXY_ENABLE_VIDEO_THUMBNAILS config option.

  • IMGPROXY_ENABLE_VIDEO_THUMBNAILS: when true, enables video thumbnail generation. Default: false
  • IMGPROXY_VIDEO_THUMBNAIL_SECOND: the timestamp of the frame (in seconds) that will be used for the thumbnail. Default: 1.

Colorspace and HDR preservation

imgproxy always preserves the source image's colorspace:

  • Color images remain color images.
  • Grayscale images remain grayscale images.
  • Colorspace types are maintained.

The bit depth handling depends on the IMGPROXY_PRESERVE_HDR configuration setting:

When IMGPROXY_PRESERVE_HDR is enabled:

  • High bit images remain high bit in the output (eg, GRAYSCALE16 remains GRAYSCALE16, RGB16 stays RGB16, scRGB becomes RGB16)

When IMGPROXY_PRESERVE_HDR is disabled (default):

  • High bit images are converted to 8-bit (eg, GRAYSCALE16 becomes GRAYSCALE8, RGB, RGB16 and scRGB become sRGB)
  • 8-bit images remain 8-bit