ImageMagick in Python with Wand

ImageMagick is a command-line and library suite for converting, editing, and composing images. In Python, the most common way to use ImageMagick directly is through Wand, a ctypes-based binding to the MagickWand API.

Use Wand when you specifically need ImageMagick features such as broad format support, PDF/image conversion, advanced transforms, or compatibility with an existing ImageMagick workflow. For simple image tasks, Pillow may be easier. For numerical image data, NumPy and OpenCV may fit better.

What ImageMagick can do

The official ImageMagick website describes ImageMagick as an open-source suite for creating, editing, composing, and converting bitmap images. It supports common formats such as JPEG, PNG, GIF, TIFF, and many others. ImageMagick can resize, crop, rotate, blur, sharpen, annotate, compose, and batch-process images from scripts.

Wand exposes many of those features through Python objects. The official Wand documentation says Wand requires Python 3.8 or newer and the MagickWand library from ImageMagick.

Install ImageMagick and Wand

Wand is not a pure-Python image library. You need both the Python package and the ImageMagick system library.

Ubuntu or Debian

sudo apt update
sudo apt install imagemagick
python -m pip install Wand

macOS with Homebrew

brew install imagemagick
python -m pip install Wand

On Apple Silicon Macs, Wand may need MAGICK_HOME set if Python cannot find the ImageMagick library:

export MAGICK_HOME=/opt/homebrew

Windows

Install the ImageMagick Windows binary from the official download page, choose the build that matches your Python architecture, and include development headers/libraries during installation. Then install Wand:

py -m pip install Wand

The Wand installation guide covers platform-specific details, including MAGICK_HOME and Windows architecture matching. If Python itself is not found, use this fix for Python not recognized on Windows.

Verify the installation

Check the Python package first:

python -m pip show Wand

Then run a short import test:

from wand.image import Image

print(Image)

If you see an error such as ImportError: MagickWand shared library not found, Wand is installed but Python cannot find the ImageMagick library. Recheck the system install, architecture, and MAGICK_HOME setting.

Open an image and read its size

Use a context manager so the file handle and ImageMagick resources are released properly:

from wand.image import Image

with Image(filename="input.jpg") as img:
    print(img.width, img.height, img.format)

The wand.image reference lists the methods and properties available on image objects.

Convert JPG to PNG

To convert an image, open it, set the output format, and save it with the new filename:

from wand.image import Image

with Image(filename="input.jpg") as img:
    img.format = "png"
    img.save(filename="output.png")

For simple conversion jobs, the ImageMagick command-line tool can also be enough:

magick input.jpg output.png

Resize an image

This example resizes an image to 800 pixels wide while keeping the original aspect ratio:

from wand.image import Image

with Image(filename="input.jpg") as img:
    new_width = 800
    new_height = int(img.height * new_width / img.width)
    img.resize(new_width, new_height)
    img.save(filename="resized.jpg")

If you are comparing ImageMagick with Pillow workflows, see our guide on converting a PIL image to a NumPy array.

Crop an image

Wand’s crop() method takes boundaries. This example keeps a 400 by 300 area starting at x=100 and y=50:

from wand.image import Image

with Image(filename="input.jpg") as img:
    img.crop(left=100, top=50, right=500, bottom=350)
    img.save(filename="cropped.jpg")

Rotate or flip an image

Rotate an image by degrees:

from wand.image import Image

with Image(filename="input.jpg") as img:
    img.rotate(90)
    img.save(filename="rotated.jpg")

Flip an image vertically or flop it horizontally:

from wand.image import Image

with Image(filename="input.jpg") as img:
    img.flip()
    img.save(filename="flipped.jpg")

with Image(filename="input.jpg") as img:
    img.flop()
    img.save(filename="flopped.jpg")

For a Pillow-based approach, see our guide to rotating an image in Python.

Blur an image

Use blur() with a radius and sigma. A higher sigma creates a stronger blur:

from wand.image import Image

with Image(filename="input.jpg") as img:
    img.blur(radius=0, sigma=3)
    img.save(filename="blurred.jpg")

Add a text watermark

Use wand.drawing.Drawing and wand.color.Color to draw text on the image:

from wand.color import Color
from wand.drawing import Drawing
from wand.image import Image

with Image(filename="input.jpg") as img:
    with Drawing() as draw:
        draw.font_size = 42
        draw.fill_color = Color("rgba(255, 255, 255, 0.75)")
        draw.text(40, img.height - 60, "Python Pool")
        draw(img)

    img.save(filename="watermarked.jpg")

Convert PDF to images carefully

ImageMagick can work with PDFs when the required delegate tools, often Ghostscript, are installed. On many systems PDF reading is restricted by ImageMagick’s security policy. Do not relax PDF security rules for untrusted uploads without understanding the risk.

from wand.image import Image

with Image(filename="document.pdf", resolution=200) as pdf:
    for index, page in enumerate(pdf.sequence):
        with Image(page) as img:
            img.format = "png"
            img.save(filename=f"page-{index + 1}.png")

ImageMagick’s own site advises creating a security policy that fits your environment. If you only need to create PDFs from text, this guide on Python text to PDF covers another route.

Common errors

• MagickWand shared library not found: ImageMagick is missing, installed for the wrong architecture, or not discoverable through standard library paths.
• PDF not authorized: ImageMagick’s security policy blocks PDF reading. Install the needed delegate and review the policy before changing it.
• Command works in terminal but not Python: Python may be running in a different environment. Use python -m pip show Wand and check MAGICK_HOME.
• Slow processing: Resize images before expensive effects, process batches carefully, and avoid loading huge images unless needed.

When to use Wand vs Pillow

If your goal is only to display an image inside a plot, our Matplotlib imshow guide is more relevant than ImageMagick.

Conclusion

ImageMagick in Python is powerful when you need ImageMagick’s format support and transformation engine from Python code. Install ImageMagick first, install Wand second, use context managers, and keep security policy in mind for PDFs and untrusted files. For smaller everyday image edits, compare Wand with Pillow before adding a system-level dependency.