Imagemagick

ImageMagick Skill

ImageMagick is a comprehensive, free, open-source software suite for creating, editing, converting, and manipulating images in over 250 formats. This skill covers command-line usage of ImageMagick tools for programmatic image processing.

When to Use This Skill

Use this skill when:

• Converting images between formats (PNG, JPEG, WebP, GIF, etc.)
• Resizing, cropping, or transforming images
• Applying effects, filters, or adjustments to images
• Creating thumbnails or image previews
• Batch processing multiple images
• Compositing or combining images
• Adding watermarks, borders, or text to images
• Optimizing images for web or print

Core Concepts

Primary Commands

ImageMagick provides several command-line tools:

• magick: Modern unified command for all operations (ImageMagick v7+)
• convert: Legacy command for image conversion and manipulation (still widely used)
• mogrify: Modify images in-place (batch processing)
• identify: Display image metadata and properties
• montage: Create image composites and contact sheets
• composite: Overlay images

Note: In ImageMagick v7+, magick is the recommended command. Legacy convert syntax: convert input.png output.jpg becomes magick input.png output.jpg

Command Structure

Basic syntax:

magick [input-options] input-file [operations] [output-options] output-file

Operations are applied left to right in the order specified.

Geometry Specifications

ImageMagick uses geometry strings for dimensions:

• 100x100 - Resize to fit within 100×100 (maintains aspect ratio)
• 100x100! - Force exact size (ignores aspect ratio)
• 100x100^ - Fill 100×100 (may crop, maintains aspect ratio)
• 100x - Resize to width 100 (auto height)
• x100 - Resize to height 100 (auto width)
• 50% - Scale to 50% of original
• 100x100+10+20 - 100×100 region at offset (10, 20)

Installation

macOS:

brew install imagemagick

Ubuntu/Debian:

sudo apt-get install imagemagick

Verify installation:

magick -version
# or
convert -version

Common Operations

Format Conversion

Convert between image formats:

# PNG to JPEG
magick input.png output.jpg

# JPEG to WebP
magick input.jpg output.webp

# Multiple formats
magick input.png output.jpg output.webp output.gif

# Set JPEG quality (0-100)
magick input.png -quality 85 output.jpg

# Convert with compression
magick input.png -quality 90 -strip output.jpg

Resizing

Resize images while maintaining aspect ratio:

# Resize to fit within 800×600
magick input.jpg -resize 800x600 output.jpg

# Resize to specific width (auto height)
magick input.jpg -resize 800x output.jpg

# Resize to specific height (auto width)
magick input.jpg -resize x600 output.jpg

# Resize to exact dimensions (ignores aspect ratio)
magick input.jpg -resize 800x600! output.jpg

# Scale by percentage
magick input.jpg -resize 50% output.jpg

# Resize only if larger (shrink only)
magick input.jpg -resize 800x600\> output.jpg

# Resize only if smaller (enlarge only)
magick input.jpg -resize 800x600\< output.jpg

Cropping

Extract portions of images:

# Crop 400×400 pixels starting at (100, 100)
magick input.jpg -crop 400x400+100+100 output.jpg

# Crop from center
magick input.jpg -gravity center -crop 400x400+0+0 output.jpg

# Remove virtual canvas after crop
magick input.jpg -crop 400x400+100+100 +repage output.jpg

# Crop to aspect ratio from center
magick input.jpg -gravity center -crop 16:9 output.jpg

Resize + Crop (Thumbnail Generation)

Common pattern for creating square thumbnails:

# Resize to fill 100×100, then crop from center
magick input.jpg -resize 100x100^ -gravity center -extent 100x100 output.jpg

# Alternative using crop
magick input.jpg -resize 275x275^ -gravity center -crop 275x275+0+0 +repage output.jpg

# Create thumbnail with specific background
magick input.jpg -resize 100x100 -background white -gravity center -extent 100x100 output.jpg

Effects and Filters

Apply visual effects:

# Blur
magick input.jpg -blur 0x8 output.jpg

# Gaussian blur with radius 5, sigma 3
magick input.jpg -gaussian-blur 5x3 output.jpg

# Sharpen
magick input.jpg -sharpen 0x1 output.jpg

# Grayscale
magick input.jpg -colorspace Gray output.jpg

# Sepia tone
magick input.jpg -sepia-tone 80% output.jpg

# Negate (invert colors)
magick input.jpg -negate output.jpg

# Edge detection
magick input.jpg -edge 3 output.jpg

# Emboss
magick input.jpg -emboss 2 output.jpg

# Oil painting effect
magick input.jpg -paint 4 output.jpg

# Charcoal drawing
magick input.jpg -charcoal 2 output.jpg

Adjustments

Modify brightness, contrast, and colors:

# Adjust brightness (+/- 0-100)
magick input.jpg -brightness-contrast 10x0 output.jpg

# Adjust contrast
magick input.jpg -brightness-contrast 0x20 output.jpg

# Both brightness and contrast
magick input.jpg -brightness-contrast 10x20 output.jpg

# Adjust saturation
magick input.jpg -modulate 100,150,100 output.jpg

# Adjust hue
magick input.jpg -modulate 100,100,120 output.jpg

# Auto level (normalize contrast)
magick input.jpg -auto-level output.jpg

# Auto gamma correction
magick input.jpg -auto-gamma output.jpg

# Normalize (stretch histogram)
magick input.jpg -normalize output.jpg

Rotation and Flipping

Transform image orientation:

# Rotate 90 degrees clockwise
magick input.jpg -rotate 90 output.jpg

# Rotate 180 degrees
magick input.jpg -rotate 180 output.jpg

# Rotate counter-clockwise
magick input.jpg -rotate -90 output.jpg

# Rotate with background color
magick input.jpg -background white -rotate 45 output.jpg

# Flip vertically
magick input.jpg -flip output.jpg

# Flip horizontally (mirror)
magick input.jpg -flop output.jpg

# Auto-orient based on EXIF
magick input.jpg -auto-orient output.jpg

Borders and Frames

Add borders to images:

# Add 10px black border
magick input.jpg -border 10x10 output.jpg

# Add border with specific color
magick input.jpg -bordercolor red -border 10x10 output.jpg

# Add frame effect
magick input.jpg -mattecolor gray -frame 10x10+5+5 output.jpg

# Add shadow effect
magick input.jpg \( +clone -background black -shadow 80x3+5+5 \) \
  +swap -background white -layers merge +repage output.jpg

Text and Watermarks

Add text overlays:

# Add simple text
magick input.jpg -pointsize 30 -fill white -annotate +10+30 "Hello" output.jpg

# Add text with positioning
magick input.jpg -gravity south -pointsize 20 -fill white \
  -annotate +0+10 "Copyright 2025" output.jpg

# Add text with background
magick input.jpg -gravity center -pointsize 40 -fill white \
  -undercolor black -annotate +0+0 "Watermark" output.jpg

# Add semi-transparent watermark
magick input.jpg \( -background none -fill "rgba(255,255,255,0.5)" \
  -pointsize 50 label:"DRAFT" \) -gravity center -compose over -composite output.jpg

Compositing

Combine multiple images:

# Overlay watermark on image
magick input.jpg watermark.png -gravity southeast -composite output.jpg

# Overlay with transparency
magick input.jpg watermark.png -gravity center \
  -compose over -composite output.jpg

# Tile pattern
magick input.jpg pattern.png -compose over -tile -composite output.jpg

# Side-by-side images
magick input1.jpg input2.jpg +append output.jpg

# Stack images vertically
magick input1.jpg input2.jpg -append output.jpg

Format-Specific Options

Optimize for different formats:

# JPEG with quality and strip metadata
magick input.png -quality 85 -strip output.jpg

# Progressive JPEG
magick input.png -quality 85 -interlace Plane output.jpg

# PNG with compression level (0-9)
magick input.jpg -quality 95 output.png

# WebP with quality
magick input.jpg -quality 80 output.webp

# WebP lossless
magick input.png -define webp:lossless=true output.webp

# GIF with optimization
magick input.png -colors 256 output.gif

# Transparent background PNG
magick input.jpg -transparent white output.png

Batch Processing

Using mogrify

Modify multiple files in-place:

# Convert all JPEGs to PNG in current directory
mogrify -format png *.jpg

# Resize all images in directory
mogrify -resize 800x600 *.jpg

# Apply to output directory (preserves originals)
mogrify -path ./output -resize 800x600 *.jpg

# Batch thumbnail generation
mogrify -path ./thumbnails -resize 275x275^ -gravity center \
  -crop 275x275+0+0 +repage *.jpg

# Batch format conversion with quality
mogrify -path ./optimized -format jpg -quality 85 -strip *.png

Using shell loops

For more complex batch operations:

# Convert with custom naming
for img in *.jpg; do
  magick "$img" -resize 800x600 "resized_$img"
done

# Multi-step processing
for img in *.jpg; do
  magick "$img" -resize 1920x1080^ -gravity center \
    -crop 1920x1080+0+0 +repage -quality 85 "processed_$img"
done

# Different output format
for img in *.png; do
  magick "$img" -quality 90 "${img%.png}.jpg"
done

Image Information

Using identify

Get image metadata:

# Basic info
identify image.jpg

# Detailed information
identify -verbose image.jpg

# Format only
identify -format "%f: %wx%h %b\n" image.jpg

# Specific attributes
identify -format "%f: %wx%h, %[colorspace], %[type]\n" image.jpg

# File size
identify -format "%f: %b\n" image.jpg

# Multiple images
identify *.jpg

Common format strings

• %f - filename
• %w - width
• %h - height
• %b - file size
• %[colorspace] - colorspace
• %[type] - image type
• %[channels] - number of channels
• %[depth] - bit depth

Advanced Techniques

Creating Contact Sheets

Use montage:

# Basic grid
montage *.jpg -geometry 200x200+2+2 contact-sheet.jpg

# With labels
montage *.jpg -geometry 200x200+2+2 -label '%f' contact-sheet.jpg

# Custom layout (3 columns)
montage *.jpg -tile 3x -geometry 200x200+5+5 contact-sheet.jpg

Animated GIFs

Create animations:

# Create GIF from images
magick -delay 100 -loop 0 frame*.png animated.gif

# Optimize GIF
magick animated.gif -fuzz 5% -layers Optimize optimized.gif

# Extract frames from GIF
magick animated.gif frame_%03d.png

Complex Pipelines

Chain multiple operations:

# Resize, crop, add border, adjust brightness
magick input.jpg \
  -resize 1000x1000^ \
  -gravity center \
  -crop 1000x1000+0+0 +repage \
  -bordercolor black -border 5x5 \
  -brightness-contrast 5x10 \
  -quality 90 \
  output.jpg

# Create thumbnail with watermark
magick input.jpg \
  -resize 400x400^ \
  -gravity center \
  -extent 400x400 \
  \( watermark.png -resize 100x100 \) \
  -gravity southeast -geometry +10+10 \
  -composite \
  output.jpg

Performance Optimization

Memory and Speed

# Limit memory usage (useful for large images)
magick -limit memory 2GB -limit map 4GB input.jpg -resize 50% output.jpg

# Set thread count
magick -limit thread 4 input.jpg -resize 50% output.jpg

# Use streaming for large files
magick -define stream:buffer-size=0 huge.jpg -resize 50% output.jpg

Quality vs Size Trade-offs

# High quality (larger file)
magick input.jpg -quality 95 output.jpg

# Balanced (recommended for web)
magick input.jpg -quality 85 -strip output.jpg

# Lower quality (smaller file)
magick input.jpg -quality 70 -sampling-factor 4:2:0 -strip output.jpg

# Progressive JPEG (better for web)
magick input.jpg -quality 85 -interlace Plane -strip output.jpg

Common Patterns

Avatar/Profile Picture Generation

# Square thumbnail from any aspect ratio
magick input.jpg -resize 200x200^ -gravity center -extent 200x200 avatar.jpg

# Circular avatar (PNG with transparency)
magick input.jpg -resize 200x200^ -gravity center -extent 200x200 \
  \( +clone -threshold -1 -negate -fill white -draw "circle 100,100 100,0" \) \
  -alpha off -compose copy_opacity -composite avatar.png

Responsive Images

# Generate multiple sizes
for size in 320 640 1024 1920; do
  magick input.jpg -resize ${size}x -quality 85 "output-${size}w.jpg"
done

Watermarking

# Bottom-right watermark
magick input.jpg watermark.png -gravity southeast \
  -geometry +10+10 -composite output.jpg

# Tiled watermark
magick input.jpg \( watermark.png -alpha set -channel A \
  -evaluate multiply 0.3 +channel \) -tile -composite output.jpg

Error Handling

Common issues and solutions:

File not found:

# Check file exists
[ -f input.jpg ] && magick input.jpg output.png || echo "File not found"

Invalid geometry:

# Validate dimensions first
identify -format "%wx%h" input.jpg

Memory errors:

# Limit resources
magick -limit memory 1GB -limit map 2GB input.jpg output.png

Best Practices

1. Always use -strip to remove metadata (reduces file size)
2. Set appropriate quality (85 for JPEG is good balance)
3. Use +repage after crop to reset virtual canvas
4. Quote file paths with spaces: "my image.jpg"
5. Test on sample before batch processing
6. Backup originals when using mogrify
7. Use -auto-orient to respect EXIF orientation
8. Progressive JPEGs for web (use -interlace Plane)
9. Limit memory for large batches to prevent crashes
10. Check output after complex operations

Troubleshooting

Policy Restrictions

Some systems restrict ImageMagick operations for security:

# Check policy
identify -list policy

# Edit policy file (if needed)
sudo nano /etc/ImageMagick-6/policy.xml
# or
sudo nano /etc/ImageMagick-7/policy.xml

Common Errors

"convert: not authorized"

• ImageMagick security policy blocking operation
• Edit policy.xml to allow specific formats/operations

"convert: no decode delegate"

• Missing format support library
• Install additional libraries (libjpeg, libpng, libwebp, etc.)

"convert: memory allocation failed"

• Image too large or insufficient memory
• Use -limit flags or process in smaller chunks

Resources

• Official Documentation: https://imagemagick.org/
• Command-line Options: https://imagemagick.org/script/command-line-options.php
• Examples: https://imagemagick.org/Usage/
• Format Support: https://imagemagick.org/script/formats.php

Command Reference Quick Guide

Format Conversion:

magick input.ext output.ext

Resize:

magick input.jpg -resize WIDTHxHEIGHT output.jpg

Crop:

magick input.jpg -crop WIDTHxHEIGHT+X+Y output.jpg

Thumbnail:

magick input.jpg -resize 100x100^ -gravity center -extent 100x100 thumb.jpg

Effects:

magick input.jpg -blur 0x8 output.jpg

Batch:

mogrify -resize 800x600 *.jpg

Info:

identify -verbose image.jpg