kovidgoyal/kitty · error · OSError

Failed to find the ImageMagick convert executable, make sure

Error message

Failed to find the ImageMagick convert executable, make sure it is present in PATH

What it means

Raised by render_image when neither the 'magick' executable nor the legacy 'convert' executable is found via which(). Unlike error 35 this check happens up front, before any subprocess is spawned, when building the conversion command line.

Source

Thrown at kittens/tui/images.py:197

    available_width: int,
    available_height: int,
    scale_up: bool,
    only_first_frame: bool = False,
    remove_alpha: str = '',
    flip: bool = False,
    flop: bool = False,
) -> RenderedImage:
    import tempfile

    has_multiple_frames = len(m) > 1
    get_multiple_frames = has_multiple_frames and not only_first_frame
    exe = which('magick')
    if exe:
        cmd = [exe, 'convert']
    else:
        exe = which('convert')
        if exe is None:
            raise OSError('Failed to find the ImageMagick convert executable, make sure it is present in PATH')
        cmd = [exe]
    if remove_alpha:
        cmd += ['-background', remove_alpha, '-alpha', 'remove']
    else:
        cmd += ['-background', 'none']
    if flip:
        cmd.append('-flip')
    if flop:
        cmd.append('-flop')
    cmd += ['--', path]
    if only_first_frame and has_multiple_frames:
        cmd[-1] += '[0]'
    cmd.append('-auto-orient')
    scaled = False
    width, height = m.width, m.height
    if scale_up:
        if width < available_width:
            r = available_width / width

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Install ImageMagick so that magick or convert is in PATH
2. Check with 'which magick convert' in the same environment the kitten runs in (kitty's env, not your shell)
3. Pre-check with shutil.which('magick') or shutil.which('convert') before calling render_image and fall back to a placeholder

Example fix

# before
frame = render_image(p, w)  # OSError
# after
import shutil
if shutil.which('magick') or shutil.which('convert'):
    frame = render_image(p, w)
else:
    frame = placeholder(p)

import shutil
if shutil.which('magick') is None and shutil.which('convert') is None:
    raise SystemExit('ImageMagick not found in PATH')

import shutil
from typing import Optional
def find_imagemagick() -> Optional[str]:
    return shutil.which('magick') or shutil.which('convert')

try:
    frame = render_image(p, w)
except OSError as e:
    if 'ImageMagick convert executable' in str(e):
        frame = None
    else:
        raise

When it happens

Trigger: Calling render_image(path, ...) on a system where ImageMagick 7 ('magick') and ImageMagick 6 ('convert') are both absent from PATH.

Common situations: Minimal Docker images (alpine, slim) without ImageMagick; headless servers used for kitten image previews; PATH differences between interactive shells and the environment kitty/kittens run in.

Related errors

• ImageMagick is required to process images
• ImageMagick failed to convert {} correctly, it generated {}
• Unexpected output filename: {x!r} produced by ImageMagick co
• Failed to render {len(unseen)} out of {len(m)} frames of ani
• You are missing the {args[0]} program needed to generate the

AI-assisted analysis of kovidgoyal/kitty@6d5d0c4406 (2026-08-27). Data as JSON: /api/errors/d1e68e5dcf405923. Report an issue: GitHub.