{"record":{"id":"d1e68e5dcf405923","repo":"kovidgoyal/kitty","slug":"failed-to-find-the-imagemagick-convert-executable","errorCode":null,"errorMessage":"Failed to find the ImageMagick convert executable, make sure it is present in PATH","messagePattern":"Failed to find the ImageMagick convert executable, make sure it is present in PATH","errorType":"exception","errorClass":"OSError","httpStatus":null,"severity":"error","filePath":"kittens/tui/images.py","lineNumber":197,"sourceCode":"    available_width: int,\n    available_height: int,\n    scale_up: bool,\n    only_first_frame: bool = False,\n    remove_alpha: str = '',\n    flip: bool = False,\n    flop: bool = False,\n) -> RenderedImage:\n    import tempfile\n\n    has_multiple_frames = len(m) > 1\n    get_multiple_frames = has_multiple_frames and not only_first_frame\n    exe = which('magick')\n    if exe:\n        cmd = [exe, 'convert']\n    else:\n        exe = which('convert')\n        if exe is None:\n            raise OSError('Failed to find the ImageMagick convert executable, make sure it is present in PATH')\n        cmd = [exe]\n    if remove_alpha:\n        cmd += ['-background', remove_alpha, '-alpha', 'remove']\n    else:\n        cmd += ['-background', 'none']\n    if flip:\n        cmd.append('-flip')\n    if flop:\n        cmd.append('-flop')\n    cmd += ['--', path]\n    if only_first_frame and has_multiple_frames:\n        cmd[-1] += '[0]'\n    cmd.append('-auto-orient')\n    scaled = False\n    width, height = m.width, m.height\n    if scale_up:\n        if width < available_width:\n            r = available_width / width","sourceCodeStart":179,"sourceCodeEnd":215,"githubUrl":"https://github.com/kovidgoyal/kitty/blob/6d5d0c440603ad9bdf6dcd599f73f6dde21acb44/kittens/tui/images.py#L179-L215","documentation":"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.","triggerScenarios":"Calling render_image(path, ...) on a system where ImageMagick 7 ('magick') and ImageMagick 6 ('convert') are both absent from PATH.","commonSituations":"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.","solutions":["Install ImageMagick so that magick or convert is in PATH","Check with 'which magick convert' in the same environment the kitten runs in (kitty's env, not your shell)","Pre-check with shutil.which('magick') or shutil.which('convert') before calling render_image and fall back to a placeholder"],"exampleFix":"# before\nframe = render_image(p, w)  # OSError\n# after\nimport shutil\nif shutil.which('magick') or shutil.which('convert'):\n    frame = render_image(p, w)\nelse:\n    frame = placeholder(p)","handlingStrategy":"validation","validationCode":"import shutil\nif shutil.which('magick') is None and shutil.which('convert') is None:\n    raise SystemExit('ImageMagick not found in PATH')","typeGuard":"import shutil\nfrom typing import Optional\ndef find_imagemagick() -> Optional[str]:\n    return shutil.which('magick') or shutil.which('convert')","tryCatchPattern":"try:\n    frame = render_image(p, w)\nexcept OSError as e:\n    if 'ImageMagick convert executable' in str(e):\n        frame = None\n    else:\n        raise","preventionTips":["Verify executables exist in the environment the kitten runs in, not just your shell","Add ImageMagick to container/CI images"],"tags":["imagemagick","missing-dependency","executable-not-found"],"backgroundTag":"missing-external-dependency","analyzedSha":"6d5d0c440603ad9bdf6dcd599f73f6dde21acb44","analyzedAt":"2026-08-27T14:20:20.142Z","schemaVersion":2},"datasetVersion":"2026-08-27T19:17:21.184Z"}