MiniMax-AI/skills · critical · SystemExit

ERROR: ffmpeg not found. Install via: brew install ffmpeg /

Error message

ERROR: ffmpeg not found. Install via: brew install ffmpeg / apt install ffmpeg

What it means

check_ffmpeg() found no `ffmpeg` executable on PATH (shutil.which returns None). The converter shells out to ffmpeg for a two-pass palette GIF conversion, so the binary is a hard runtime dependency. This is a pure environment/dependency problem, not a logic error.

Source

Thrown at skills/gif-sticker-maker/scripts/convert_mp4_to_gif.py:23

Usage:
  python convert_mp4_to_gif.py sticker_hi.mp4 sticker_laugh.mp4 sticker_cry.mp4 sticker_love.mp4
  python convert_mp4_to_gif.py *.mp4 --fps 12 --width 320
  python convert_mp4_to_gif.py input.mp4 -o custom_output.gif

Requires: ffmpeg (must be on PATH)
"""

import os
import sys
import argparse
import subprocess
import shutil


def check_ffmpeg():
    if not shutil.which("ffmpeg"):
        raise SystemExit("ERROR: ffmpeg not found. Install via: brew install ffmpeg / apt install ffmpeg")


def mp4_to_gif(input_path: str, output_path: str, fps: int = 15, width: int = 360):
    """Convert a single MP4 to GIF via ffmpeg two-pass (palette for quality)."""
    if not os.path.isfile(input_path):
        print(f"SKIP: {input_path} not found", file=sys.stderr)
        return False

    palette = output_path + ".palette.png"
    scale_filter = f"fps={fps},scale={width}:-1:flags=lanczos"

    try:
        subprocess.run(
            ["ffmpeg", "-y", "-i", input_path,
             "-vf", f"{scale_filter},palettegen=stats_mode=diff",
             palette],
            check=True, capture_output=True,
        )

View on GitHub (pinned to 60aaae52bb)

Solutions

Install ffmpeg: macOS `brew install ffmpeg`, Debian/Ubuntu `sudo apt install ffmpeg`, Alpine `apk add ffmpeg`.
If already installed, ensure its directory is on PATH for the process: `export PATH="$PATH:/path/to/ffmpeg/bin"`.
In Docker, add `RUN apt-get update && apt-get install -y ffmpeg` (or the apk/yum equivalent).
Verify quickly: `python -c "import shutil;print(shutil.which('ffmpeg'))"` should print a path, not None.

Example fix

// before: shell without ffmpeg
$ python convert_mp4_to_gif.py clip.mp4 -o out.gif
ERROR: ffmpeg not found.

// after
$ brew install ffmpeg   # or: sudo apt install ffmpeg
$ python convert_mp4_to_gif.py clip.mp4 -o out.gif

Defensive patterns

Strategy: validation

Validate before calling

import shutil

def ensure_ffmpeg():
    """Fail fast with an actionable message if ffmpeg isn't on PATH."""
    if not shutil.which("ffmpeg"):
        raise EnvironmentError("ffmpeg not found — install it (brew/apt/apk) or add its dir to PATH")
    return True

Type guard

def ffmpeg_available() -> bool:
    """True when an ffmpeg executable is resolvable on PATH."""
    return shutil.which("ffmpeg") is not None

Try / catch

import subprocess, sys
try:
    subprocess.run([sys.executable, "convert_mp4_to_gif.py", mp4, "-o", gif], check=True, capture_output=True, text=True)
except subprocess.CalledProcessError as e:
    if "ffmpeg not found" in (e.stderr or ""):
        raise EnvironmentError("install ffmpeg first (brew install ffmpeg / apt install ffmpeg)") from e
    raise

Prevention

Add ffmpeg to your base image (Dockerfile `RUN apt-get install -y ffmpeg`) so it's always present.
Run `python -c "import shutil;print(shutil.which('ffmpeg'))"` as a preflight in CI.
Ensure the shell PATH is inherited by the Python process (avoid `env -i` or stripped env).
Pin a known ffmpeg version in CI to avoid breakage from upstream changes.

When it happens

Trigger: Running convert_mp4_to_gif.py on a machine/CI image without ffmpeg installed, or where ffmpeg is installed but not on the PATH visible to the Python process.

Common situations: Slim Docker/CI image without ffmpeg; macOS without `brew install ffmpeg`; a venv/subprocess that doesn't inherit the shell PATH where ffmpeg lives; ffmpeg installed under a different name or only as a static binary not on PATH.

Related errors

AI-assisted analysis of MiniMax-AI/skills@60aaae52bb (2026-08-13). Data as JSON: /api/errors/5940b1857e1ce1f7. Report an issue: GitHub.