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

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

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 (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 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.

Converting animated images to MP4 Pro

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

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