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.
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.
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:falseIMGPROXY_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 and scRGB become sRGB)
- 8-bit images remain 8-bit