docling-project/docling · error · RuntimeError

FFmpeg is required for video processing but was not found on

Error message

FFmpeg is required for video processing but was not found on PATH. Install it with your system package manager (e.g., 'brew install ffmpeg' on macOS, 'apt-get install ffmpeg' on Linux, 'winget install ffmpeg' on Windows).

What it means

RuntimeError raised by _require_ffmpeg() in docling/utils/video_frame_sampling.py when shutil.which('ffmpeg') finds no ffmpeg executable on PATH. Video frame sampling (fixed-interval sampling and scene detection) shells out to ffmpeg to decode frames, so the binary is a hard runtime dependency for any video input, unlike the pure-Python document converters.

Source

Thrown at docling/utils/video_frame_sampling.py:70

    scene_id: int | None = Field(
        None, description="Scene index if produced by a scene sampler."
    )


class VideoScene(BaseModel):
    """A contiguous time window treated as one scene."""

    model_config = ConfigDict(arbitrary_types_allowed=True)

    scene_id: int
    start_time: float = Field(..., ge=0)
    end_time: float = Field(..., ge=0)
    representative_frame: VideoFrame | None = None


def _require_ffmpeg() -> None:
    if shutil.which("ffmpeg") is None:
        raise RuntimeError(MISSING_FFMPEG_MESSAGE)


# Auto-prominence calibration. The frame-diff signal is mostly ambient motion
# (near-zero for static screen shares, elevated for podcasts/vlogs where people
# move constantly) with sparse spikes at genuine scene cuts.
_AUTO_PROMINENCE_FLOOR: Final[float] = 0.012
"""Minimum auto threshold. Keeps static footage sensitive to subtle cuts while
staying above codec noise (~0.005-0.01). Below this, tiny diffs are ignored."""

_AUTO_PROMINENCE_K: Final[float] = 5.0
"""Robust sigmas above ambient motion a peak must clear to count as a cut.
Higher = stricter (fewer scenes on busy video); lower = more sensitive."""


def _auto_prominence(diffs: np.ndarray) -> float:
    """Adapt the scene-cut threshold to how busy the video is.

    Uses the median frame difference as the ambient-motion floor and the

View on GitHub (pinned to 61d76f1ff3)

Solutions

Install ffmpeg with the system package manager: 'apt-get install ffmpeg' (Debian/Ubuntu), 'brew install ffmpeg' (macOS), 'winget install ffmpeg' (Windows).
If ffmpeg is installed but not found, add its directory to PATH or invoke Python from a shell where 'ffmpeg --version' succeeds.
In Dockerfiles, add 'RUN apt-get update && apt-get install -y --no-install-recommends ffmpeg' (or 'apt-get install -y ffmpeg' in the final stage) and rebuild.
Optionally check availability up front with shutil.which('ffmpeg') and fail fast with a clear message before submitting video jobs.

Example fix

# Dockerfile (before): plain python image, ffmpeg missing
FROM python:3.12-slim
RUN pip install docling

# after
FROM python:3.12-slim
RUN apt-get update && apt-get install -y --no-install-recommends ffmpeg && rm -rf /var/lib/apt/lists/*
RUN pip install docling

Defensive patterns

Strategy: validation

Validate before calling

import shutil

if shutil.which("ffmpeg") is None:
    raise RuntimeError("ffmpeg not on PATH; install it before processing video")
frames = sampler.sample(video_path)

Try / catch

try:
    frames = sampler.sample(video_path)
except RuntimeError as exc:
    if "ffmpeg" in str(exc):
        raise SystemExit("Install ffmpeg (apt-get install ffmpeg) and retry") from exc
    raise

Prevention

Precheck 'ffmpeg -version' (or shutil.which('ffmpeg')) when video inputs are configured, not at first sample call.
Bake ffmpeg into Docker images and CI runners used for video processing.
Document ffmpeg as a system prerequisite for any workflow that accepts video files.

When it happens

Trigger: Instantiating FixedIntervalFrameSampler(...).sample(video_path) or the scene-detection sampler's sample() on a machine where ffmpeg is not installed or not on PATH — including minimal Docker images, slim CI runners, and Windows systems where ffmpeg was downloaded but not added to PATH.

Common situations: Running Docling's video pipeline inside a python:* slim Docker image (no ffmpeg preinstalled); CI environments without system packages; conda/venv setups where ffmpeg was installed into a different environment than the one running Docling; Windows installs where the zip was extracted but PATH was never updated.

Related errors

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/07ba539faaba18a6. Report an issue: GitHub.