# imagick compatibility lines map to ImageMagick versions, and memory is yours to free > imagick is a cgo binding to ImageMagick's MagickWand C API, maintained as parallel version lines so each tracks a different generation of ImageMagick. The two things that cause real bugs are picking the wrong line and mixing constructor styles, because the Go garbage collector does not own the C memory underneath. **gographics/imagick** — Go binding to ImageMagick's MagickWand C API - Repository: https://github.com/gographics/imagick - Website: https://godoc.org/github.com/gographics/imagick/imagick - Stars: 1,878 · Forks: 186 - Language: Go - License: NOASSERTION - Published: 2026-10-16 · Updated: 2026-10-16 · Language: en - Canonical page: https://hysenlabs.com/projects/gographics-imagick ## Three branches, three gopkg.in paths, one rule The most important thing in the README is the compatibility block, because choosing wrong here produces compile or link errors that do not explain themselves. ```text im-7 (tag v3.x.x): 7.x <= ImageMagick <= 7.x master (tag v2.x.x): 6.9.1-7 <= ImageMagick <= 6.9.9-35 legacy (tag v1.x.x): 6.7.x <= ImageMagick <= 6.8.9-10 ``` Each line maps to a separate import path through gopkg.in: gopkg.in/gographics/imagick.v3/imagick, gopkg.in/gographics/imagick.v2/imagick and gopkg.in/gographics/imagick.v1/imagick. So selecting a version is selecting an import path, not a dependency constraint, and the two are not interchangeable. Recent tags show both the v3 and v2 lines still being maintained: v3.7.3 and v2.7.1 were both released on 2026-02-17, with v3.7.2 from 2024-12-16 before them. The default branch is master, which is the ImageMagick 6 line. That is a detail worth flagging to anyone arriving from the repository's landing page: the newest feature work is on im-7, not on what you get by default. The last push was on 2026-05-31. ## Installing the native library is the first half of the work This is a cgo binding, so the build needs ImageMagick's development files present, and the README covers each platform separately. On macOS: ```bash brew install imagemagick ``` On Ubuntu and Debian: ```bash sudo apt-get install libmagickwand-dev ``` Then confirm pkg-config can find the headers and libraries: ```bash pkg-config --cflags --libs MagickWand ``` That check is worth running before anything else, because a silent failure there shows up much later as linker errors. There is one environment variable that will bite you for a non-obvious reason. Following a Go security update, you may need to allow the -Xpreprocessor flag: ```bash export CGO_CFLAGS_ALLOW='-Xpreprocessor' ``` And if you are building statically or deliberately without pkg-config, there is a build tag for supplying CGO_CFLAGS and CGO_LDFLAGS yourself: ```bash go build -tags no_pkgconfig gopkg.in/gographics/imagick.v2/imagick ``` A Docker path exists too, with an example under examples/docker. The repository's own Dockerfile is a more complete reference for a working native stack: it starts from golang:1.23, installs pkg-config plus the format development libraries for jpeg, png, tiff and gif, fontconfig, ghostscript and freetype, then builds ImageMagick from source with configure flags that turn off Magick++, Perl and OpenMP, and enable fontconfig, freetype and gslib. Its final command is `go test -v ./imagick`, so the container is a test harness rather than an application image. ## Initialize once, Terminate once, or expect crashes The README is unusually direct about this, and the directness should be taken literally. As in the C API, `Initialize()` should be called only once to set up resources, typically in `main()` or an `init()` for the whole application. Applications can defer `Terminate()` to tear things down. The warning that follows matters: it is an error to Initialise and Terminate multiple times in specific functions, and doing so leads to common problems such as crashes or missing delegates. Do not call Terminate anywhere other than the absolute end of your need for ImageMagick. A Go application with several goroutines and a request-scoped helper is exactly where this mistake happens, because the natural instinct is to bracket each operation with Initialize and Terminate. A process-level initialization pattern looks like this: ```go package main import "gopkg.in/gographics/imagick.v2/imagick" func main() { imagick.Initialize() defer imagick.Terminate() mw := imagick.NewMagickWand() defer mw.Destroy() // Use mw here. } ``` The two calls are process-scoped, not operation-scoped. ## Never mix struct literals with New constructors Because this is a cgo binding and the Go GC does not manage memory allocated by the C API, resources have to be released explicitly, and the rule is about consistency rather than about which style is better. Objects created through `New*` constructors, such as MagickWand, DrawingWand, PixelIterator and PixelWand, and objects returned by methods such as `Clone()`, are managed by the Go GC through finalizers. That cleanup is not immediate; it happens whenever the GC runs its finalizers, which may be much later than the point where you stopped using the object. Objects created with struct literals are not. Those need `Destroy()` called by hand: ```go mw := imagick.MagickWand{...} defer mw.Destroy() ``` Both cleanup approaches are compatible when constructor methods are used. Calling Destroy on a constructor-made object is allowed and recommended because it forces immediate cleanup instead of waiting for the GC: ```go mw := imagick.NewMagickWand() defer mw.Destroy() ``` What is explicitly forbidden is mixing. Creating one wand with a struct literal and another with `New*`, in the same program, is called out in the README as something you should not do, because the two objects then have different lifetime rules and the finalizer-based path can free something the manual path expects to own. The practical guidance is that in a long-running service, explicitly calling Destroy is good practice, because how often the GC runs is not under your control and a server that converts images on every request will accumulate C memory until it decides otherwise. ## Windows needs MSYS2 and a coder path, and the codec error is the tell The Windows instructions are contributed separately and stored in their own README, which is a hint that they are maintained separately too. The shape is: install msys2-x86_64, then install the toolchain and ImageMagick from the msys shell. ```bash pacman -S mingw-w64-x86_64-gcc pacman -S mingw-w64-x86_64-pkg-config pacman -S mingw-w64-x86_64-zlib pacman -S mingw-w64-x86_64-imagemagick ``` Then switch to cmd.exe and set three environment variables, where `` must be replaced with your actual msys2 installation path, whose default is `C:\msys64`: ```bash set PATH=\mingw64\bin;%PATH% set PKG_CONFIG_PATH=\mingw64\lib\pkgconfig set MAGICK_CODER_MODULE_PATH=\mingw64\lib\ImageMagick-7.0.6\modules-Q16HDRI\coders go build gopkg.in/gographics/imagick.v3/imagick ``` The third variable is the one that explains a confusing runtime failure. `MAGICK_CODER_MODULE_PATH` tells ImageMagick where its decoders live, and if you still hit `NoDecodeDelegateForThisImageFormat`, the README says to check that the version number and the folders in the path are correct. Note that the sample path hardcodes an ImageMagick 7.0.6 modules directory, so a different ImageMagick build needs a matching path rather than a copied one. The examples directory is worth knowing about as documentation: it holds usage examples ported from the C ones in the MagickWand documentation, covering resize, affine, morphology, pixel_mod, floodfill, fontmetrics, text effects, masks and more. ## Conclusion imagick fits a Go service that must reuse ImageMagick's existing delegate coverage for exotic formats rather than reimplementing decoders, and whose deployment can carry a native library. It does not fit a pure-Go build, since cgo is mandatory, or a static binary without deliberate effort, in which case the no_pkgconfig build tag and explicit CGO flags become your problem. Verify first that pkg-config resolves MagickWand on the target machine, call imagick.Initialize() exactly once at process start, and pick the gopkg.in line that matches the ImageMagick version you actually installed rather than the newest tag. ## FAQ ### How do I install the imagick Go binding? Install the native library first: `brew install imagemagick` on macOS or `sudo apt-get install libmagickwand-dev` on Ubuntu and Debian, then check `pkg-config --cflags --libs MagickWand` resolves before fetching the Go package. ### Which imagick version should I use for my ImageMagick install? Pick by ImageMagick generation. Tag v3.x.x on the im-7 branch targets ImageMagick 7.x, v2.x.x on master targets 6.9.1-7 through 6.9.9-35, and v1.x.x on legacy targets 6.7.x through 6.8.9-10. They map to gopkg.in/gographics/imagick.v3, .v2 and .v1. ### Why does imagick leak or crash in a long-running Go service? Two documented causes. The Go GC does not manage memory allocated by the C API, so calling Destroy() explicitly releases it sooner instead of waiting for a finalizer. And Initialize() and Terminate() must each happen only once for the whole process, not per request. ### What does the no_pkgconfig build tag do? It lets you supply CGO_CFLAGS and CGO_LDFLAGS manually at build time, which is useful when building statically or when pkg-config is not available. The documented usage is `go build -tags no_pkgconfig gopkg.in/gographics/imagick.v2/imagick`. ### Why do I get NoDecodeDelegateForThisImageFormat on Windows? MAGICK_CODER_MODULE_PATH tells ImageMagick where to find its decoders. The README says to make sure the version number and folders in that path are correct, since the sample path hardcodes an ImageMagick 7.0.6 modules directory. ### Can I mix struct literals and New constructors in imagick? No. The README explicitly says not to mix the two ways of object creation, because objects made with New* are cleaned up by GC finalizers while struct literals need a manual Destroy call, and the two lifetime rules differ. ## Sources - [gographics/imagick on GitHub](https://github.com/gographics/imagick) - [Issues](https://github.com/gographics/imagick/issues) - [Project website](https://godoc.org/github.com/gographics/imagick/imagick) - [README](https://github.com/gographics/imagick/blob/master/README.md) - [Releases](https://github.com/gographics/imagick/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/gographics-imagick