imgproxy — Fast Secure Image Processing Server in Go

Introduction

imgproxy is a fast, secure standalone server for resizing, cropping, and converting remote images. Written in Go and powered by libvips, it processes images on-the-fly without storing anything on disk. It is designed to be a drop-in image CDN backend that protects your infrastructure from image-based attacks while delivering optimized images at scale.

What imgproxy Does

• Resizes, crops, rotates, and watermarks images via URL-based processing pipelines
• Converts between formats including WebP, AVIF, JPEG, PNG, GIF, and HEIC automatically
• Signs URLs with HMAC to prevent unauthorized image processing requests
• Fetches source images from HTTP, S3, GCS, Azure Blob, or local filesystem
• Serves responsive images with automatic format negotiation based on Accept headers

Architecture Overview

imgproxy runs as a single stateless Go binary behind a reverse proxy or CDN. Incoming requests encode processing instructions in the URL path. The server fetches the source image, pipes it through libvips for transformation, and streams the result directly to the client. There is no disk cache by default — images are processed in memory. A URL signature scheme using HMAC-SHA256 prevents abuse. The server supports graceful shutdown, health checks, and Prometheus metrics.

Self-Hosting & Configuration

• Deploy via Docker or prebuilt binaries; single container, no dependencies
• Set IMGPROXY_KEY and IMGPROXY_SALT env vars to enable URL signing
• Configure IMGPROXY_MAX_SRC_RESOLUTION to cap maximum source image size
• Enable IMGPROXY_USE_S3=true with AWS credentials to fetch from S3 buckets
• Tune IMGPROXY_CONCURRENCY and IMGPROXY_MAX_ANIMATION_FRAMES for load control

Key Features

• Processes images in under 50ms for typical web sizes using libvips
• URL signing prevents denial-of-wallet attacks from arbitrary processing requests
• Automatic WebP/AVIF serving based on browser Accept header negotiation
• Supports animated GIF and WebP processing without frame extraction
• Built-in Prometheus metrics and structured JSON logging for observability

Comparison with Similar Tools

• Thumbor — Python-based, slower; imgproxy is 5-10x faster with Go and libvips
• Cloudinary — managed SaaS with broader features; imgproxy is free and self-hosted
• sharp (Node.js) — library, not a server; imgproxy provides a complete HTTP service
• Imaginary — similar Go server; imgproxy has more formats and better security model

FAQ

Q: How does URL signing work? A: You generate an HMAC-SHA256 signature from the processing path using your key and salt. The signature is prepended to the URL, and imgproxy rejects requests with invalid signatures.

Q: Can imgproxy replace a CDN? A: No — place a CDN like CloudFront or Fastly in front of imgproxy. imgproxy handles transformation; the CDN handles caching and edge distribution.

Q: Does imgproxy support PDF and SVG? A: Yes. It can render PDF pages and SVG files to raster formats for processing.

Q: What happens if a source image is too large? A: imgproxy returns a 422 error if the image exceeds IMGPROXY_MAX_SRC_RESOLUTION, protecting against memory exhaustion.

Sources

• https://github.com/imgproxy/imgproxy
• https://docs.imgproxy.net