| description | Learn about image formats supported by imgproxy |
|---|
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 | ❌ |
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.
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.
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. :::
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 (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 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.
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.
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.
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:
- 16-bit images remain 16-bit in the output (eg. GRAYSCALE16 remains GRAYSCALE16, scRGB remains scRGB)
When IMGPROXY_PRESERVE_HDR is disabled (default):
- 16-bit images are converted to 8-bit (eg. GRAYSCALE16 becomes GRAYSCALE8, RGB and scRGB become sRGB)
- 8-bit images remain 8-bit