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 | ✅ | ❌ |
| PSD pro | psd | 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.
imgproxy reads some amount of bytes to check if the source image is SVG. By default it reads a maximum of 32KB, but you can change this:
IMGPROXY_MAX_SVG_CHECK_BYTES: the maximum number of bytes imgproxy will read to recognize SVG. If imgproxy can't recognize your SVG, try to increase this number. Default:32768(32KB)
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.
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.
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.