---
name: media-imagemagick
description: >
  Image manipulation with ImageMagick (magick / convert / mogrify / composite / identify / montage): resize, crop, rotate, convert between 200+ formats, compose layers with alpha, add text, apply effects, batch process folders, color operations, PDF/PSD/HEIC/AVIF/JXL support. Use when the user asks to process images, resize photos, convert image formats, composite layers, build a photo montage, add text to an image, apply a filter, or batch convert an image folder.
argument-hint: "[operation]"
---

# Media Imagemagick

**Context:** $ARGUMENTS

## Quick start

- **Resize / thumbnail:** → Step 2 `resize`
- **Change format (PNG→JPG/WebP/HEIC):** → Step 2 `convert`
- **Overlay logo / watermark:** → Step 2 `composite`
- **Contact-sheet grid:** → Step 2 `montage`
- **PDF → PNGs, GIF → frames:** → Step 2 format-specific recipes
- **Probe dimensions / metadata:** → Step 4 `identify`
- **Batch a folder:** → Step 2 `mogrify` / `batch-resize`

## When to use

- Resize / compress / re-encode one image or a whole folder.
- Convert between JPEG, PNG, WebP, HEIC, AVIF, JXL, TIFF, GIF, BMP, ICO, PDF, PSD.
- Compose / watermark / annotate / make contact sheets or social-media multi-size bundles.
- Script-level image plumbing where Photoshop-class apps are overkill and plain Python PIL is too limited.

Not for: raster painting (use Krita), RAW development (use darktable/RawTherapee), video (use ffmpeg — see `ffmpeg-*` skills).

## Step 1 — Install + verify

```bash
# macOS
brew install imagemagick

# Debian/Ubuntu
sudo apt install imagemagick

# Verify. On v7 the command is `magick`. v6 uses `convert`/`mogrify`/`composite` as separate binaries.
magick -version
magick -list format | head        # enumerate supported formats on this build
magick -list format | grep -Ei '^ *(HEIC|AVIF|JXL|WEBP) '   # confirm optional formats
```

- v7+ is `magick <subcommand>` (e.g. `magick convert`, `magick identify`, `magick mogrify`, `magick composite`, `magick montage`, `magick compare`). Bare `convert` still works on v7 (aliased), but ALWAYS prefer `magick` — `convert` also collides with a Windows built-in.
- HEIC / AVIF / JXL support depends on the build shipping with libheif / libavif / libjxl. If missing, rebuild from source or use a Homebrew tap / apt backport that bundles them.
- ImageMagick ships with a security policy at `/etc/ImageMagick-7/policy.xml` (or `/opt/homebrew/etc/ImageMagick-7/policy.xml` on macOS) that by default can block `PDF`, `MVG`, `LABEL`, `HTTPS`, and set low memory/disk limits. If you see `not authorized` errors, edit that file or run with `-define registry:temporary-path=...` / `--security-policy` override.

## Step 2 — Pick your operation

All recipes below are v7 `magick` form. Chain multiple ops by listing them in order; ImageMagick applies left-to-right.

### Format conversion

```bash
magick in.png out.jpg                          # format decided by extension
magick in.heic out.webp
magick in.tif -quality 85 out.jpg              # JPEG quality 85
magick in.png -define webp:lossless=true out.webp
magick in.jpg -define heic:speed=2 out.heic    # slower = smaller
magick in.jpg -strip -interlace Plane out.jpg  # strip EXIF + progressive JPEG (web-friendly)
```

### Resize / thumbnail / fit

Geometry suffix decides behavior — see `references/imagemagick.md` for the full matrix.

```bash
magick in.jpg -resize 1920x1080 out.jpg                    # fit inside, keep aspect
magick in.jpg -resize 1920x1080! out.jpg                   # force exact, ignore aspect (distorts)
magick in.jpg -resize 1920x1080^ -gravity center -extent 1920x1080 out.jpg  # fill + center-crop
magick in.jpg -resize '1920x1080>' out.jpg                 # shrink only if larger
magick in.jpg -resize 50%     out.jpg                      # percent
magick in.jpg -thumbnail 200x200 out.jpg                   # -thumbnail = -resize + -strip, much faster
```

### Crop / rotate / orient

```bash
magick in.jpg -crop 800x600+100+50 +repage out.jpg         # WxH+X+Y from top-left; +repage clears virtual canvas
magick in.jpg -rotate 90 out.jpg
magick in.jpg -rotate '90>' out.jpg                        # only if wider than tall (quirk: use sparingly)
magick in.jpg -auto-orient out.jpg                         # apply EXIF Orientation and clear tag
magick in.jpg -flop out.jpg                                # horizontal mirror
magick in.jpg -flip out.jpg                                # vertical mirror
```

### Text / annotate

```bash
magick in.jpg -font DejaVu-Sans -pointsize 72 -fill white \
              -gravity SouthEast -annotate +20+20 '© 2026' out.jpg
magick in.jpg -pointsize 48 -fill 'rgba(255,255,255,0.8)' \
              -draw "text 10,100 'Hello'" out.jpg
magick -list font | head              # discover available fonts (fontconfig on Linux, system on macOS)
```

Unicode glyphs need a font that ships them — Arial often lacks CJK/emoji; prefer `DejaVu-Sans`, `Noto-Sans-CJK`, or `Apple-Color-Emoji` depending on the glyph set.

### Composite / overlay / watermark

```bash
magick base.png logo.png -geometry +10+10 -composite out.png        # top-left @ 10,10
magick base.png logo.png -gravity SouthEast -geometry +20+20 -composite out.png
magick base.png \( logo.png -alpha set -channel A -evaluate set 40% \) \
       -gravity SouthEast -geometry +20+20 -composite out.png        # 40% opacity watermark
```

### Montage / contact sheet

```bash
magick montage *.jpg -geometry 200x200+5+5 -tile 4x4 grid.jpg
magick montage -label '%f' *.jpg -geometry 200x200+5+5 -tile 4x4 \
               -background '#222' -fill white grid.jpg               # labeled
```

### Color / tone

```bash
magick in.jpg -modulate 110,120,100 out.jpg          # brightness, saturation, hue (100 = no change)
magick in.jpg -level 10%,90% out.jpg                 # black point / white point stretch
magick in.jpg -brightness-contrast 10x20 out.jpg     # +10 brightness, +20 contrast
magick in.jpg -colorspace Gray out.jpg               # desaturate
magick in.jpg -profile sRGB.icc out.jpg              # embed / convert ICC profile
```

### Animated GIF ↔ frames

```bash
magick in.gif -coalesce frame_%04d.png                                      # explode (keep full frames)
magick -delay 10 -loop 0 frame_*.png -layers Optimize out.gif               # assemble + optimize
```

### PDF ↔ images

```bash
magick -density 300 in.pdf page_%03d.png                 # ALWAYS put -density BEFORE -input for vector/PDF
magick page_*.png out.pdf                                # images → multi-page PDF
```

If you get `attempt to perform an operation not allowed by the security policy 'PDF'`, edit policy.xml (see Gotchas).

### In-place batch (`mogrify`)

```bash
mogrify -resize 1080 *.jpg                               # OVERWRITES originals
mogrify -path thumbs/ -resize 400x400 -quality 82 *.jpg  # safer: write into thumbs/
```

Or from Python via `scripts/image.py batch-resize`.

## Step 3 — Run

Prefer the Python wrapper for repeatable, scriptable work — it echoes the exact `magick` command and supports `--dry-run`.

```bash
python3 ${CLAUDE_SKILL_DIR}/scripts/image.py check
python3 ${CLAUDE_SKILL_DIR}/scripts/image.py resize --input in.jpg --output out.jpg --width 1920 --fit inside --quality 85
python3 ${CLAUDE_SKILL_DIR}/scripts/image.py batch-resize --indir photos/ --outdir thumbs/ --width 1080 --verbose
python3 ${CLAUDE_SKILL_DIR}/scripts/image.py identify --input in.jpg
```

For one-off exploration, run `magick` directly. For anything you will repeat, put it behind a subcommand in `scripts/image.py`.

## Step 4 — Verify with `identify`

```bash
magick identify in.jpg                                                # brief
magick identify -format "%w x %h  %m  Q=%Q  %[colorspace]\n" in.jpg   # scriptable one-liner
magick identify -verbose in.jpg | less                                # full EXIF / channels / histogram
magick identify -format "%[EXIF:*]" in.jpg                            # just EXIF
magick compare -metric RMSE a.png b.png null:                         # pixel-diff two images (lower = more similar)
```

Always `identify` the output after a transform to confirm dimensions, colorspace, and quality landed where you expected.

## Reference docs

- Read [`references/imagemagick.md`](references/imagemagick.md) for the full geometry / gravity / format / color-op / security-policy cheat-sheet and recipe book.

## Gotchas

- **v7 vs v6 commands.** v7 uses the unified `magick` binary (`magick convert …`, `magick identify …`). v6 exposes `convert`, `mogrify`, `composite`, `identify`, `montage`, `compare` as separate binaries. On v7, bare `convert` still works but is deprecated and collides with a Windows system tool — ALWAYS use `magick`.
- **Security policy blocks formats.** `/etc/ImageMagick-7/policy.xml` (or the Homebrew path) restricts `PDF`, `PS`, `EPS`, `MVG`, `LABEL`, `HTTPS`, and caps memory/disk. `not authorized` errors come from here. Either edit the policy (comment out the offending `<policy domain="coder" rights="none" pattern="PDF" />` line) or pass `--security-policy /path/to/loose.xml`.
- **Geometry suffix matters.** `100x100` (fit inside), `100x100!` (force exact — distorts), `100x100^` (fill, larger of the two), `100x100>` (shrink only if larger), `100x100<` (enlarge only if smaller), `50%` (scale). Mix up `!` and `^` and you either stretch or crop by accident.
- **Coordinate system is top-left origin.** `+X+Y` in `-crop`, `-geometry`, `-annotate`, `-draw` offsets are from top-left. `-gravity` re-anchors which corner offsets are measured from (NorthWest default).
- **`mogrify` overwrites originals in place.** ALWAYS pass `-path outdir/` to redirect, or back up first. This has eaten people's photo libraries.
- **`-density` must come BEFORE the input for vector/PDF.** `magick -density 300 in.pdf out.png` rasterizes at 300 DPI. Put it after and it's a no-op on the input.
- **`-strip` deletes all EXIF/XMP/IPTC.** Great for web (privacy + filesize), terrible if the client needs camera metadata. `-thumbnail` implicitly strips.
- **`-interlace Plane` = progressive JPEG / interlaced PNG.** Smaller perceived-load times on the web; slightly larger file.
- **Fonts need fontconfig on Linux.** `-font Arial` may silently fall back if Arial isn't installed. `magick -list font` shows what's usable. On macOS, system fonts work; on Alpine/Docker, install `fontconfig` + `ttf-dejavu`.
- **Unicode / emoji rendering.** Default font won't render CJK or emoji. Use `-font Noto-Sans-CJK-Regular`, `-font Apple-Color-Emoji`, or a font that covers your glyphs, or text falls back to tofu boxes.
- **HEIC/AVIF/JXL are optional.** Build must include libheif / libavif / libjxl. Check with `magick -list format | grep HEIC`. Homebrew's build includes them; Debian's default `imagemagick` does not always.
- **Q8 vs Q16 build.** Q8 stores 8 bits/channel internally; Q16 stores 16. For HDR, ICC profile-accurate work, or 16-bit TIFF / PNG, install the Q16 build (`brew install imagemagick` ships Q16 HDRI by default; check `magick -version`).
- **Memory limits.** Large images (huge PSDs, giant PDFs) can exhaust policy-defined memory limits and spill to disk. Raise with `export MAGICK_MEMORY_LIMIT=8GiB MAGICK_MAP_LIMIT=16GiB MAGICK_DISK_LIMIT=32GiB` or edit policy.xml.
- **Parallel batch.** ImageMagick itself is mostly single-threaded per image. Use GNU `parallel` or `xargs -P` for folder-level parallelism: `find . -name '*.jpg' | parallel magick {} -resize 1080 out/{/.}.jpg`.
- **`+repage` after crop.** `-crop` leaves a "virtual canvas" so the cropped piece remembers its original offset — multi-page formats or GIFs will act weird. Append `+repage` to clear it.

## Examples

### Example 1 — Web thumbnail batch

Input: `photos/*.jpg` full-res DSLR output.
Run:

```bash
mkdir -p thumbs
mogrify -path thumbs/ -thumbnail 400x400^ -gravity center -extent 400x400 \
        -quality 82 -strip -interlace Plane photos/*.jpg
```

Result: 400×400 center-cropped JPEGs, EXIF stripped, progressive, in `thumbs/`.

### Example 2 — Watermarked social bundle

Input: `hero.jpg`, `logo.png`.
Run:

```bash
for size in 1080x1080 1080x1350 1920x1080 1200x630; do
  magick hero.jpg -resize "${size}^" -gravity center -extent "$size" \
         \( logo.png -resize 10% \) -gravity SouthEast -geometry +24+24 -composite \
         "hero_${size}.jpg"
done
```

Result: one square (IG feed), one portrait (IG/TikTok), one landscape (YouTube thumb), one OG-image (og:image), each watermarked bottom-right.

### Example 3 — Render a PDF for review

```bash
magick -density 200 report.pdf -background white -alpha remove -alpha off report_%03d.png
```

Result: one PNG per page at 200 DPI, flattened over white (prevents transparent pages from looking black).

## Troubleshooting

### Error: `attempt to perform an operation not allowed by the security policy 'PDF'`

Cause: ImageMagick's policy.xml blocks PDF (and PS/EPS) by default.
Solution: Edit `/etc/ImageMagick-7/policy.xml` (or `$(brew --prefix)/etc/ImageMagick-7/policy.xml`), comment out `<policy domain="coder" rights="none" pattern="PDF" />`. Or run with `--security-policy /path/to/loose.xml` pointing at an edited copy.

### Error: `no decode delegate for this image format 'HEIC'`

Cause: Build lacks libheif. Check with `magick -list format | grep HEIC`.
Solution: `brew reinstall imagemagick` on macOS (Homebrew builds with libheif). On Debian, install `imagemagick` from bookworm-backports or build from source with `--with-heic`.

### Error: `convert: unable to read font` or output has wrong font

Cause: Named font not installed / fontconfig cache stale.
Solution: `magick -list font` to see what's available. Install the font (macOS: drop into `~/Library/Fonts`; Linux: `apt install fonts-dejavu` then `fc-cache -fv`). Then reference by the name `magick -list font` prints (e.g. `DejaVu-Sans`, not `DejaVu Sans.ttf`).

### Error: `cache resources exhausted` / `width or height exceeds limit`

Cause: policy.xml memory/disk/area caps too low for your image (common with huge PSDs, scanned TIFFs, multi-page PDFs).
Solution: Edit policy.xml `<policy domain="resource" name="memory" value="…"/>` entries upward, or set env vars `MAGICK_MEMORY_LIMIT`, `MAGICK_DISK_LIMIT`, `MAGICK_AREA_LIMIT`, `MAGICK_WIDTH_LIMIT`, `MAGICK_HEIGHT_LIMIT`.

### Error: output image looks stretched after `-resize`

Cause: Used `!` suffix (force exact) instead of default fit-inside.
Solution: Drop the `!`. If you need exact WxH without distortion, use `-resize WxH^ -gravity center -extent WxH` (fill + crop).

### Error: cropped PNG/GIF has wrong size / stray offset

Cause: `-crop` set a virtual canvas; writer preserved it.
Solution: Add `+repage` after `-crop`.


---
Source attribution: damionrashford
Original project: https://github.com/damionrashford/media-os/blob/5014c1e8b23fd3e18d49926d9aa147d15a3aa08e/skills/media-imagemagick/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2026 Media OS

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: damionrashford
Original project: https://github.com/damionrashford/media-os/blob/5014c1e8b23fd3e18d49926d9aa147d15a3aa08e/skills/media-imagemagick/SKILL.md
Attribution basis: Source repository record

Fields of work: Content & Media, Design
Roles: Graphic Designer, UX Designer, Video Producer
Specialties: Backend
Tools: ImageMagick
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 30f575c19946e68f93126c2ae04fa90463a5512b7ca920498396e056d12f555e