Optimize GIF Images

About GIF processing

What is it? GIF processing lets Image Optimizer handle animated and static GIF files. You can keep animation, extract a static preview frame, resize/crop frames, apply watermarking, and optionally convert output to WebP.

Enable GIF processing

GIF processing is included in Image Optimizer. Configure behavior with environment variables and query parameters.

Via environment variables

FORMATS_TO_TRANSFORM=jpg,jpeg,png,gif,svg

GIF_MODE=static      # Default: process GIF as first composed frame only
GIF_MODE=animated    # Keep animation frames

CONVERT_TO_WEBP=true # Optional: convert output to WebP when browser supports it

Via query parameters

image.gif?gif_mode=animated
image.gif?gif_mode=static
image.gif?gif_mode=animated&fmt=webp

gif_mode in query overrides GIF_MODE for that request.

GIF output behavior

Mode	Requested format	Result
`static`	default	Single-frame GIF (first composed frame)
`static`	`fmt=webp`	Single-frame WebP (if `Accept` supports WebP)
`animated`	default	Animated GIF
`animated`	`fmt=webp`	Animated WebP (if `Accept` supports WebP)

Usage examples

<!-- Keep original animation -->
<img src="banner.gif?gif_mode=animated" alt="Animated banner" />

<!-- Create static preview frame -->
<img src="banner.gif?gif_mode=static" alt="Static banner" />

<!-- Animated GIF to animated WebP -->
<img src="banner.gif?gif_mode=animated&fmt=webp" alt="Animated banner" />

<!-- Animated GIF with resize and crop -->
<img src="banner.gif?gif_mode=animated&width=800&crop=16:9" alt="Optimized banner" />

Check HTTP headers

curl -I -H "Accept: image/webp,*/*" \
  https://your-cdn.com/banner.gif?gif_mode=animated&fmt=webp

Expected headers:

Content-Type: image/webp
X-Img-Operations: conversion (plus other operations when resize/crop/watermark is used)
Vary: Accept

Limitations

Memory and time safeguards

GIF processing runs with a memory budget and safety checks for large frames.
Very long or very large animated GIFs may be truncated to stay within runtime limits.

Error fallback

If GIF decode/encode fails, the original image is served.

See limitations.md for platform-level details.

Troubleshooting

Animation missing: Set GIF_MODE=animated or add ?gif_mode=animated. fmt=webp not applied: Check the request Accept header includes image/webp. Large GIF partially processed: Reduce source dimensions/frame count.

Recommended configuration

FORMATS_TO_TRANSFORM=jpg,jpeg,png,gif,svg
GIF_MODE=animated
CONVERT_TO_WEBP=true