A fluent image processing library for Go. Package-level functions, functional options, and a delayed error on Image keep chains short and concurrent-friendly.
Uses only the Go standard library and official golang.org/x/image packages. No CGO.
package main
import (
"log"
goimage "github.com/yunkeweb/go-image"
)
func main() {
img := goimage.Open("photo.jpg").
Cover(400, 300).
Greyscale().
Sharpen(10)
if err := img.Err(); err != nil {
log.Fatal(err)
}
if err := img.ToJPEG(85).Save("out.jpg"); err != nil {
log.Fatal(err)
}
}go get github.com/yunkeweb/go-imageRequires Go 1.22+. golang.org/x/image is kept at versions that still compile with Go 1.22 (v0.24.0 and earlier). v0.25.0 needs Go 1.23; v0.46.0 needs Go 1.26.
- Open / Decode / New: path,
io.Reader,[]byte,image.Image, or a blank canvas - Animate multi-frame GIFs
- Geometry:
Resize(400)orResize(400, 300); Cover / Crop / Pad withWithAnchor - Effects: Greyscale, Invert, Brightness, Contrast, Gamma, Colorize, Blur, Sharpen, Pixelate, Rotate, Flip, Flop, Orient
- Draw: pixel, rectangle, ellipse, circle, polygon, line, bezier, flood fill
- Place watermarks with 9-point alignment and opacity
- Text with TTF/OTF files or the built-in bitmap face
- Encode JPEG, PNG, GIF (including animation), WebP (lossless VP8L), BMP, TIFF;
WriteTofor HTTP - Clone deep-copies pixels for concurrent pipelines (
Imageis not concurrent-safe) - sync.Pool for NRGBA buffers, with a 16 MiB put cap for large images
- Subpackages:
modifier/(geometry, effects, drawing, GIF),encoder/(codecs),internal/(pool and color tables). Callers still import onlygithub.com/yunkeweb/go-image
canvas := goimage.New(800, 600)
photo := goimage.Open("input.png")
fromReader := goimage.Decode(r)
fromBytes := goimage.DecodeBytes(raw)
fromStd := goimage.FromImage(stdImg)
img := goimage.Open("photo.jpg", goimage.WithAutoOrientation(true))| Function | Input |
|---|---|
Open |
filesystem path (string) |
Decode |
io.Reader |
DecodeBytes |
encoded []byte |
DecodeDataURI |
data:image/...;base64,... |
FromImage |
image.Image |
New |
canvas width and height |
Animate |
frame builder callback |
Functional options (WithAutoOrientation, WithDecodeAnimation, WithBlendingColor, WithStrip, WithLimits) apply to a single call. Shared settings live in Config / DefaultConfig() and attach with WithConfig. Zero Limits fields are unlimited.
img := goimage.Decode(r, goimage.WithLimits(goimage.Limits{
MaxInputBytes: 12 << 20,
MaxWidth: 4096,
MaxHeight: 4096,
MaxPixels: 4096 * 4096,
MaxFrames: 64,
}))DecodeDataURI accepts data:image/... URIs only. ;base64 is a case-insensitive flag; the payload is percent-decoded. Non-image types, unknown parameters, empty payloads, and illegal encoding set ErrDecoder.
EncodeOptions only implements JPEG Quality (default 80). Progressive, Indexed, Interlaced, non-zero Bitdepth, and Quality on non-JPEG formats return ErrNotSupported. WebP encode is lossless VP8L.
cfg := goimage.DefaultConfig()
cfg.DecodeAnimation = false
photo := goimage.Open("input.png", goimage.WithConfig(cfg))
canvas := goimage.New(800, 600, goimage.WithConfig(cfg))
anim := goimage.Animate(func(a *goimage.Animation) {
a.AddFile("frame1.png", 0.1).AddFile("frame2.png", 0.1).SetLoops(0)
}, goimage.WithConfig(cfg))Modifiers return *Image so chains stay fluent. The first failure is stored and later calls become no-ops until you inspect it:
img := goimage.Open("missing.jpg").Cover(200, 200)
if err := img.Err(); err != nil {
log.Fatal(err)
}Encode helpers return EncodedImage. Check enc.Err() or the error from Save / WriteTo. An Image is not safe for concurrent mutation; Clone() before sharing one source across goroutines.
enc := img.ToJPEG(85)
w.Header().Set("Content-Type", enc.MimeType())
_, _ = enc.WriteTo(w) // http.ResponseWriter, Gin, or any io.Writer| Format | Decode | Encode |
|---|---|---|
| JPEG | yes (EXIF Orient when auto-orientation is on) | yes (quality 1–100, default 80; ToJPEG() / ToJPEG(95)) |
| PNG | yes | yes |
| GIF | still + animated | still + animated |
| WebP | yes (x/image/webp) |
lossless VP8L |
| BMP | yes | yes |
| TIFF | yes | yes |
| AVIF / HEIC / JPEG 2000 | delayed ErrNotSupported |
delayed ErrNotSupported |
Resize(400) keeps aspect ratio. Resize(400, 300) sets both sides. Zero or negative sizes yield delayed ErrInvalidDimensions. Cover, Crop, and Pad take WithAnchor / WithBackground / WithOffset.
- Getting started
- Modifying Images
- Cookbook
- Local docs:
npm install && npm run docs:dev
gofmt -l .
go vet ./...
go test -shuffle=on ./...
go test -race ./...See RELEASE_NOTES.md for the v0.3.0 changelog, compatibility notes, and known limitations.
MIT. See LICENSE.
Thanks to Oliver Vogel and the Intervention Image contributors. Their MIT-licensed work informed the feature set of this library.