kovidgoyal/kitty · error · NoImageMagick

ImageMagick is required to process images

Error message

ImageMagick is required to process images

What it means

Raised (as NoImageMagick) by run_imagemagick when executing the ImageMagick command fails with FileNotFoundError, meaning neither 'magick' nor 'convert' was found in PATH. All image operations in this module (identify, render_image) shell out to ImageMagick, so the dependency is mandatory.

Source

Thrown at kittens/tui/images.py:130

class OutdatedImageMagick(ValueError):
    def __init__(self, detailed_error: str):
        super().__init__('ImageMagick on this system is too old ImageMagick 7+ required which was first released in 2016')
        self.detailed_error = detailed_error


last_imagemagick_cmd: Sequence[str] = ()


def run_imagemagick(path: str, cmd: Sequence[str], keep_stdout: bool = True) -> 'CompletedProcess[bytes]':
    global last_imagemagick_cmd
    import subprocess

    last_imagemagick_cmd = cmd
    try:
        p = subprocess.run(cmd, stdout=subprocess.PIPE if keep_stdout else subprocess.DEVNULL, stderr=subprocess.PIPE)
    except FileNotFoundError:
        raise NoImageMagick('ImageMagick is required to process images')
    if p.returncode != 0:
        raise OpenFailed(path, p.stderr.decode('utf-8'))
    return p


def identify(path: str) -> ImageData:
    import json

    q = (
        '{"fmt":"%m","canvas":"%g","transparency":"%A","gap":"%T","index":"%p","size":"%wx%h",'
        '"dpi":"%xx%y","dispose":"%D","orientation":"%[EXIF:Orientation]"},'
    )
    exe = which('magick')
    if exe:
        cmd = [exe, 'identify']
    else:
        cmd = ['identify']
    p = run_imagemagick(path, cmd + ['-format', q, '--', path])

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Install ImageMagick (apt install imagemagick / brew install imagemagick) and verify 'magick' or 'convert' is on PATH
2. If installed but not found, ensure kitty is launched from an environment with the correct PATH or symlink magick into a standard bin dir
3. Catch NoImageMagick and degrade gracefully (skip image preview)

Example fix

# before
img = render_image(path, width=80)  # NoImageMagick
# after
# sudo apt-get install imagemagick   (or brew install imagemagick)
img = render_image(path, width=80)

import shutil
def imagemagick_available() -> bool:
    return shutil.which('magick') is not None or shutil.which('convert') is not None

from kittens.tui.images import NoImageMagick
try:
    img = render_image(path, width=80)
except NoImageMagick:
    img = None  # image previews unsupported here

When it happens

Trigger: Calling identify(path) or render_image(...) on a machine where ImageMagick is not installed or its bin directory is not in PATH for the kitten's process.

Common situations: Fresh container/CI image without ImageMagick; macOS where 'magick' is not symlinked; PATH stripped by a service manager, sandbox, or GUI-launched kitty that doesn't inherit the shell PATH.

Related errors

• Failed to find the ImageMagick convert executable, make sure
• ImageMagick failed to convert {} correctly, it generated {}
• You are missing the {args[0]} program needed to generate the
• Failed to execute rg: %w
• %s is not a valid path with error: %w

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