Configuration
Environment variables reference
All configuration is done through environment variables.
| Variable | Default | Description |
|---|
IMAGE_PROXY_BIND_ADDRESS | 0.0.0.0:8000 | TCP address and port to listen on |
IMAGE_PROXY_ROOT_PATH | /app/data | Root directory for serving image files |
IMAGE_PROXY_STRIP_PATH | (unset) | Path prefix to strip from incoming requests. Useful when behind a reverse proxy that adds a prefix. |
RUST_LOG | INFO | Log level (TRACE, DEBUG, INFO, WARN, ERROR) |
| Variable | Default | Description |
|---|
IMAGE_PROXY_FALLBACK_IMAGE_URL | (unset) | Base URL for fetching images not found on disk (e.g., https://cdn.example.com/images/) |
IMAGE_PROXY_FALLBACK_IMAGE_MAX_SIZE | 5242880 (5 MB) | Maximum size in bytes for fallback image responses. Prevents excessive memory usage. |
IMAGE_PROXY_USER_AGENT | image-proxy/<version> | User-Agent header sent when fetching fallback images from an upstream. Loaded into EncodingConfig; empty/whitespace falls back to default. |
See Formats for details on each format's quality and speed parameters.
| Variable | Default | Range | Description |
|---|
IMAGE_PROXY_AVIF_QUALITY | 85 | 0–100 | AVIF quality |
IMAGE_PROXY_AVIF_SPEED | 6 | 1–10 | AVIF encoder speed |
IMAGE_PROXY_JPEG_QUALITY | 75 | 0–100 | JPEG quality |
IMAGE_PROXY_WEBP_QUALITY | 80 | 0–100 | WebP quality |
IMAGE_PROXY_WEBP_EFFORT | 4 | 0–6 | WebP compression effort |
IMAGE_PROXY_WEBP_LOSSLESS | false | bool | WebP lossless encoding |
IMAGE_PROXY_JXL_QUALITY | 75 | 0–100 | JPEG XL quality |
IMAGE_PROXY_JXL_SPEED | 6 | 1–10 | JPEG XL encoder speed |
IMAGE_PROXY_JXL_LOSSLESS | false | bool | JPEG XL lossless encoding |
IMAGE_PROXY_PNG_COMPRESSION_LEVEL | 6 | 0–9 | PNG compression level |
| Variable | Default | Options | Description |
|---|
IMAGE_PROXY_RESIZE_ALGORITHM | auto | auto, lanczos3, bicubic, gaussian, thumbnail | Default resize algorithm. Can be overridden per-request. |
Guards against decompression bombs and out-of-memory conditions. Set any of these to 0 to disable that specific check (not recommended).
| Variable | Default | Description |
|---|
IMAGE_PROXY_MAX_DIMENSION | 8192 | Maximum allowed image width or height in pixels. Images declaring larger dimensions are rejected before a pixel buffer is allocated. |
IMAGE_PROXY_MAX_SOURCE_SIZE | 104857600 (100 MB) | Maximum on-disk source file size in bytes. Files larger than this are rejected with 413 Payload Too Large before being read into memory. Note: this limit only applies to requests that require decoding or transformation; pass-through requests (no query parameters, source format matches the requested format) stream the file directly without loading it into memory, so the size limit does not apply to them. |
| Variable | Default | Description |
|---|
IMAGE_PROXY_PREFERRED_FORMATS | (unset) | Comma-separated list of preferred output formats for automatic format selection (e.g., avif,webp). Leaving this field empty disables automatic format selection. |
IMAGE_PROXY_ALLOWED_OUTPUT_FORMATS | (unset) | Comma-separated list of allowed output formats. Requests for unlisted formats get 415. When unset, all formats are allowed. Leaving this field empty allows all formats. |
See Caching for detailed information.
| Variable | Default | Description |
|---|
IMAGE_PROXY_ENABLE_CACHE | false | Enable response caching |
IMAGE_PROXY_CACHE_MEMORY_SIZE | 104857600 (100 MB) | In-memory cache capacity in bytes |
IMAGE_PROXY_CACHE_MAX_ITEM_SIZE | 1048576 (1 MB) | Maximum size of a single cached item. Larger items are not cached. |
IMAGE_PROXY_ENABLE_DISK_CACHE | false | Enable disk-backed cache (requires ENABLE_CACHE=true) |
IMAGE_PROXY_CACHE_DISK_SIZE | 536870912 (512 MB) | Pre-allocated disk cache capacity in bytes |
IMAGE_PROXY_CACHE_DISK_PATH | ./cache | Directory for disk cache files |
| Variable | Default | Description |
|---|
IMAGE_PROXY_CACHE_CONTROL_HEADER | public, max-age=31536000, no-transform | Value for the Cache-Control response header. Set to empty string to disable. |
IMAGE_PROXY_CACHE_STATUS_HEADER | X-Image-Proxy-Cache | Name of the response header indicating cache status (HIT/MISS). |