{"record":{"id":"5940b1857e1ce1f7","repo":"MiniMax-AI/skills","slug":"error-ffmpeg-not-found-install-via-brew-install","errorCode":null,"errorMessage":"ERROR: ffmpeg not found. Install via: brew install ffmpeg / apt install ffmpeg","messagePattern":"ERROR: ffmpeg not found\\. Install via: brew install ffmpeg / apt install ffmpeg","errorType":"exception","errorClass":"SystemExit","httpStatus":null,"severity":"critical","filePath":"skills/gif-sticker-maker/scripts/convert_mp4_to_gif.py","lineNumber":23,"sourceCode":"\nUsage:\n  python convert_mp4_to_gif.py sticker_hi.mp4 sticker_laugh.mp4 sticker_cry.mp4 sticker_love.mp4\n  python convert_mp4_to_gif.py *.mp4 --fps 12 --width 320\n  python convert_mp4_to_gif.py input.mp4 -o custom_output.gif\n\nRequires: ffmpeg (must be on PATH)\n\"\"\"\n\nimport os\nimport sys\nimport argparse\nimport subprocess\nimport shutil\n\n\ndef check_ffmpeg():\n    if not shutil.which(\"ffmpeg\"):\n        raise SystemExit(\"ERROR: ffmpeg not found. Install via: brew install ffmpeg / apt install ffmpeg\")\n\n\ndef mp4_to_gif(input_path: str, output_path: str, fps: int = 15, width: int = 360):\n    \"\"\"Convert a single MP4 to GIF via ffmpeg two-pass (palette for quality).\"\"\"\n    if not os.path.isfile(input_path):\n        print(f\"SKIP: {input_path} not found\", file=sys.stderr)\n        return False\n\n    palette = output_path + \".palette.png\"\n    scale_filter = f\"fps={fps},scale={width}:-1:flags=lanczos\"\n\n    try:\n        subprocess.run(\n            [\"ffmpeg\", \"-y\", \"-i\", input_path,\n             \"-vf\", f\"{scale_filter},palettegen=stats_mode=diff\",\n             palette],\n            check=True, capture_output=True,\n        )","sourceCodeStart":5,"sourceCodeEnd":41,"githubUrl":"https://github.com/MiniMax-AI/skills/blob/60aaae52bb2af8162732751a4332f62a5fef518b/skills/gif-sticker-maker/scripts/convert_mp4_to_gif.py#L5-L41","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before: shell without ffmpeg\n$ python convert_mp4_to_gif.py clip.mp4 -o out.gif\nERROR: ffmpeg not found.\n\n// after\n$ brew install ffmpeg   # or: sudo apt install ffmpeg\n$ python convert_mp4_to_gif.py clip.mp4 -o out.gif","handlingStrategy":"validation","validationCode":"import shutil\n\ndef ensure_ffmpeg():\n    \"\"\"Fail fast with an actionable message if ffmpeg isn't on PATH.\"\"\"\n    if not shutil.which(\"ffmpeg\"):\n        raise EnvironmentError(\"ffmpeg not found — install it (brew/apt/apk) or add its dir to PATH\")\n    return True","typeGuard":"def ffmpeg_available() -> bool:\n    \"\"\"True when an ffmpeg executable is resolvable on PATH.\"\"\"\n    return shutil.which(\"ffmpeg\") is not None","tryCatchPattern":"import subprocess, sys\ntry:\n    subprocess.run([sys.executable, \"convert_mp4_to_gif.py\", mp4, \"-o\", gif], check=True, capture_output=True, text=True)\nexcept subprocess.CalledProcessError as e:\n    if \"ffmpeg not found\" in (e.stderr or \"\"):\n        raise EnvironmentError(\"install ffmpeg first (brew install ffmpeg / apt install ffmpeg)\") from e\n    raise","preventionTips":["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."],"tags":["dependency","environment","ffmpeg","python","gif"],"backgroundTag":null,"analyzedSha":"60aaae52bb2af8162732751a4332f62a5fef518b","analyzedAt":"2026-08-13T17:32:34.717Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}