Create image collages with ImageMagick CLI

Tim Koschützki

Co-founder · Berlin, Germany ·

Pass ImageMagick an explicit list of images to make a collage in a predictable order. The Bash script below makes a PNG grid, leaves your source files unchanged, and reads only the files you list. It also refuses an existing destination, so a rerun cannot replace a collage.

Set up ImageMagick

Use Linux with Bash and an ImageMagick 7 installation that includes JPEG and PNG support. This walkthrough was tested with GNU Bash 5.3.15 and ImageMagick 7.1.2-31 Q16-HDRI. ImageMagick 6 and other operating systems are outside this example’s tested scope.

Paste the command blocks in a Bash shell with errexit disabled, so a failed command returns control to your prompt. The saved script below sets its own error handling.

Check that the tools are on your PATH:

bash --version && magick --version

Configure resource limits

Keep your installation’s existing security policy. These small examples do not require a global policy edit. You can inspect the current limits with:

magick -list resource

Larger images can still hit the configured limits even when their thumbnails are small, because decoding comes first. Use fewer or smaller source images before changing a policy. ImageMagick’s resource policy documentation explains the controls.

Prepare your images

Start in a writable directory. This block creates a new collage-demo directory with three sample JPEGs and a separate output directory. It fails if collage-demo already exists and leaves your shell in its original directory:

(
  mkdir collage-demo || exit 1
  cd collage-demo || exit 1
  mkdir photos collages || exit 1
  magick -size 320x160 xc:red photos/red.jpg &&
  magick -size 160x320 xc:lime photos/green.jpg &&
  magick -size 240x240 xc:blue photos/blue.jpg
)

Save the following script as collage-demo/make-collage.sh. Its arguments are a new .png destination followed by one or more local still JPEG or PNG files. Quote each path and list the files in the order you want them to appear. Do not use *.jpg in a directory containing generated images: the shell would include those images too.

ImageMagick has its own filename syntax, including wildcards and frame selectors. Shell quoting alone does not disable it. The script copies each input to a temporary, ordinary filename before decoding, then copies the finished PNG to your literal destination. This also handles paths containing spaces, brackets, or percent signs.

#!/usr/bin/env bash
set -euo pipefail

if (( $# < 2 )); then
  printf 'Usage: bash make-collage.sh OUTPUT.png INPUT [INPUT ...]\n' >&2
  exit 2
fi
output=$1
shift
if [[ "$output" != *.png ]]; then
  printf 'Output must end in .png: %q\n' "$output" >&2
  exit 2
fi
if [[ -e "$output" || -L "$output" ]]; then
  printf 'Refusing existing output: %q\n' "$output" >&2
  exit 1
fi

work=$(mktemp -d)
trap 'rm -rf -- "$work"' EXIT
tiles=()
for input in "$@"; do
  if [[ ! -f "$input" || ! -r "$input" ]]; then
    printf 'Not a readable file: %q\n' "$input" >&2
    exit 1
  fi
  if ! cp -- "$input" "$work/source"; then
    printf 'Cannot copy input: %q\n' "$input" >&2
    exit 1
  fi
  tile="tile-${#tiles[@]}.png"
  if ! (
    cd -- "$work" &&
    magick -regard-warnings 'source[0]' -auto-orient -colorspace sRGB \
      -thumbnail 200x200 -background white -gravity center -extent 200x200 \
      -alpha remove -alpha off -strip -depth 8 "$tile"
  ); then
    printf 'Cannot decode input: %q\n' "$input" >&2
    exit 1
  fi
  tiles+=("$tile")
done

(
  cd -- "$work" &&
  magick montage -regard-warnings "${tiles[@]}" -tile 3x \
    -geometry 200x200+2+2 -background white -strip result.png
)
cp -- "$work/result.png" "$output"
printf 'Created %q\n' "$output"

Each image fits inside a 200×200 tile without cropping or stretching; white padding fills the remaining area. Transparency is composited onto white, including partially transparent pixels. The script applies orientation metadata before resizing and converts colors to sRGB before compositing. This is a generic conversion. When accurate color matching matters, especially for CMYK or ICC-tagged images, use a suitable color profile workflow.

Use complete local images that you trust. -regard-warnings treats some decoding warnings as errors; it does not validate image integrity. On the tested build, a JPEG with a truncated payload still produced a collage and returned success, with incorrect pixels near the bottom of its tile. Check the input and the entire resulting tile when damage is possible. Only the first frame is used if an input contains a sequence.

Create a collage using montage

From the directory containing collage-demo, run:

(
  cd collage-demo &&
  bash make-collage.sh collages/example.png \
    photos/red.jpg photos/green.jpg photos/blue.jpg
)

Open collage-demo/collages/example.png. It should be 612×204 pixels, with red, green, and blue tiles from left to right. The landscape image has white padding above and below; the portrait image has padding on its sides. There are 2 pixels around each tile, giving a 4-pixel gap between neighbors. Check every tile, including its edges, when using real photographs.

Repeating this command fails with “Refusing existing output” and leaves that PNG unchanged. Choose a new destination to make another collage. The script copies the result only after every tile and the montage succeed; a filesystem error during that final copy can still leave a partial output. Run jobs sequentially: the existence check does not protect against concurrent writers to the same destination. Keep source files stable while a job runs.

Customize your layout

The script’s montage options control the grid. -tile 3x reserves three columns and uses as many rows as needed. -geometry 200x200+2+2 uses the prepared 200×200 tiles with 2 pixels of surrounding space. Four inputs produce a 612×408 image; the unused cells in the last row are white. One or two inputs still reserve three columns. To change the thumbnail size, keep -thumbnail, -extent, and the size in -geometry consistent.

Batch processing with error handling

This block creates two collages from explicitly chosen input sets. It continues after a failed job and returns a nonzero status if either job fails, even when the last one succeeds:

(
  cd collage-demo || exit 1
  status=0
  bash make-collage.sh collages/warm.png \
    photos/red.jpg photos/green.jpg || status=1
  bash make-collage.sh collages/cool.png \
    photos/green.jpg photos/blue.jpg || status=1
  exit "$status"
)

Missing and empty input files, and files that raise decoding errors, fail their job and identify the selected path in the error. Recoverable damage has the limitation described above. Passing no input paths prints the usage message. Existing outputs also count as failed jobs; successful jobs remain available.

Troubleshooting

If magick is missing, check that you installed version 7 and that its executable directory is on PATH. A missing JPEG or PNG decoder requires a build with that format enabled; installing header packages alone does not add a decoder to an existing binary.

For a failed input, read the diagnostic containing its original path, then inspect that file. For a resource-policy error, reduce the workload and consult your installation’s policy. For a failed final copy, check that the output directory exists and is writable before trying a new destination. No output directory is created automatically by the script.

Replace the sample paths with your own image list once the demonstration works. Keep the input order explicit and choose a fresh PNG destination for each collage.