imagemagick

name	imagemagick
description	Guide for using ImageMagick command-line tools to perform advanced image processing tasks including format conversion, resizing, cropping, effects, transformations, and batch operations. Use when manipulating images programmatically via shell commands.
license	MIT
version	1.0.0

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