Why does ImageMagick say unable to read font?

ImageMagick cannot resolve that font name. Run magick -list font to see what is available. If the list is empty you have no fonts installed, which is common in slim Docker images.

Why does my text render as empty boxes in ImageMagick?

The font has no glyphs for those characters. Latin fonts do not cover CJK, Arabic or emoji. Install a Noto font covering your script and pass it with -font using a full file path.

How do I use a custom font file with ImageMagick?

Pass the full path: -font /path/to/YourFont.ttf. This skips fontconfig name resolution entirely and is the most reliable option in scripts and containers.

unable to read font / text renders as empty boxes

Two font problems with one cause. How to list available fonts, install fonts in slim Docker images, and render CJK, Arabic or emoji text that shows as boxes.

convert: unable to read font `Helvetica' @ error/annotate.c/RenderFreetype/1662
convert: no decode delegate for this image format `` @ error/constitute.c

Or text renders, but every character is an empty rectangle: □□□□

Step one: what does ImageMagick know about?

magick -list font

This prints every font ImageMagick can resolve by name, with the path to each file.

Case A — the list is empty or very short

The machine has no fonts installed, or ImageMagick was built without the fontconfig delegate. Extremely common in slim Docker images, which ship no fonts at all.

apt install fonts-dejavu-core          # Debian / Ubuntu — small, good coverage
dnf install dejavu-sans-fonts          # Fedora
apk add font-dejavu                    # Alpine

Then re-run magick -list font. If it is still empty but you can see font files on disk, fontconfig is missing:

apt install fontconfig && fc-cache -f

Bypassing font lookup entirely

You can always pass a full path to a font file, which skips name resolution:

magick in.jpg -font /usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf \
  -pointsize 48 -fill white -gravity south -annotate +0+30 'Hello' out.jpg

This is the most reliable form for scripts and containers — no dependency on fontconfig's view of the world.

Case B — text renders as empty boxes

The font loaded fine; it simply has no glyphs for the characters you asked for. The standard Latin fonts do not cover Chinese, Japanese, Korean, Arabic, Hebrew, Thai, Devanagari or emoji.

apt install fonts-noto-cjk             # Chinese / Japanese / Korean
apt install fonts-noto-color-emoji     # emoji
apt install fonts-noto                 # broad Unicode coverage

magick in.jpg \
  -font /usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc \
  -pointsize 48 -fill white -gravity south -annotate +0+40 '你好世界' out.jpg

Finding a font that covers your text

fc-list :lang=zh                       # fonts covering Chinese
fc-list :lang=ar                       # Arabic
fc-match 'Noto Sans CJK SC'            # resolve a name to a file

Encoding

If non-ASCII text comes out as mojibake rather than boxes, the problem is encoding rather than fonts:

magick in.jpg -encoding UTF-8 -font NotoSansCJK-Regular \
  -pointsize 40 -annotate +20+60 '你好' out.jpg

Also check your terminal is sending UTF-8, and on Windows that the code page is set with chcp 65001. For long or awkward strings, read from a file instead of the command line:

magick in.jpg -font NotoSansCJK-Regular -pointsize 40 \
  -annotate +20+60 '@caption.txt' out.jpg

Right-to-left scripts

ImageMagick does not do full bidirectional text shaping. Arabic and Hebrew may render with unjoined letterforms or in the wrong order. If you need correct shaping, render the text with Pango — ImageMagick can use it as a source:

magick -background none pango:'<span font="Noto Sans Arabic 40">مرحبا</span>' out.png

Check magick -list format | grep -i pango first, as it is not compiled into every build.