feat(deps): make opencv optional to strip ffmpeg CVEs from [all] (#2216) (#2221)

* feat(deps): make opencv-python-headless optional (new  extra)




* refactor(deps): tighten cv2 extra placement in pyproject




* feat(deps): make vllm optional and drop from [all]




* fix(bench): install cv2/vllm at runtime per benchmark modality




* test: drop pytest.importorskip(cv2) from cv2-touching tests




* fix(deps): strip opencv from image instead of dropping vllm from [all]




* fix(docker): remove vllm import smoke test; tolerate opencv absence on arm64




---------

Signed-off-by: Dong Hyuk Chang <9426164+thomasdhc@users.noreply.github.com>
Signed-off-by: NeMo Bot <nemo-bot@nvidia.com>
Co-authored-by: Dong Hyuk Chang <9426164+thomasdhc@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 3 people

benchmarking/tools/ci_benchmark_launcher.sh

@@ -34,6 +34,13 @@ fi
 cd /opt/Curator
 uv pip install GitPython pynvml pyyaml rich
 
+# cv2 stripped from image (CVE removal); reinstall for benchmarks that need it.
+case "${ENTRY_NAME}" in
+    interleaved_*|multimodal_*|video_*)
+        uv pip install ".[cv2]"
+        ;;
+esac
+
 # Session name resolution:
 #   - If NEMO_CI_SESSION_NAME is set by the generated benchmark pipeline, use it
 #     verbatim so every benchmark job writes to the same session directory.

docker/Dockerfile

@@ -97,7 +97,9 @@ RUN if [ -n "${CURATOR_EXTRA}" ]; then \
     find /opt/venv -name "ray_dist.jar" -delete && \
     if find /opt/venv -name "ray_dist.jar" | grep -q .; then \
         echo "ERROR: GHSA-72hv-8253-57qq not fixed — ray_dist.jar still present after deletion" && exit 1; \
-    fi
+    fi && \
+    # Strip opencv-python-headless (ffmpeg CVE carrier); tolerate arm64 where vllm doesn't pull it.
+    (uv pip uninstall opencv-python-headless || true)
 
 # Install nemotron-ocr (C++/CUDA extension — requires no-build-isolation)
 # GIT_LFS_SKIP_SMUDGE=1: clone source only, model weights are mounted at runtime

nemo_curator/stages/interleaved/filter/blur_filter.py

@@ -17,13 +17,17 @@
 from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
-import cv2
 import pandas as pd
 from loguru import logger
 
 from nemo_curator.stages.interleaved.stages import BaseInterleavedFilterStage
 from nemo_curator.stages.interleaved.utils import image_bytes_to_array
 
+try:
+    import cv2
+except ImportError:
+    cv2 = None  # type: ignore[assignment]
+
 if TYPE_CHECKING:
     from collections.abc import Hashable
 
@@ -32,10 +36,16 @@
     from nemo_curator.tasks import InterleavedBatch
 
 DEFAULT_BLUR_SCORE_THRESHOLD: float = 100.0
+_CV2_INSTALL_HINT = (
+    "opencv-python-headless is required for the interleaved blur filter. "
+    "Install with: pip install nemo_curator[cv2]"
+)
 
 
 def _sharpness_score(image: np.ndarray, row_index: Hashable | None = None) -> float:
     """Compute Laplacian variance as sharpness score; higher is sharper."""
+    if cv2 is None:
+        raise ImportError(_CV2_INSTALL_HINT)
     try:
         return float(cv2.Laplacian(image, cv2.CV_64F).var())
     except cv2.error as e:

nemo_curator/stages/interleaved/filter/qrcode_filter.py

@@ -17,24 +17,34 @@
 from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
-import cv2
 import numpy as np
 import pandas as pd
 from loguru import logger
 
 from nemo_curator.stages.interleaved.stages import BaseInterleavedFilterStage
 from nemo_curator.stages.interleaved.utils import image_bytes_to_array
 
+try:
+    import cv2
+except ImportError:
+    cv2 = None  # type: ignore[assignment]
+
 if TYPE_CHECKING:
     from collections.abc import Hashable
 
     from nemo_curator.tasks import InterleavedBatch
 
 DEFAULT_QRCODE_SCORE_THRESHOLD: float = 0.05
+_CV2_INSTALL_HINT = (
+    "opencv-python-headless is required for the interleaved QR code filter. "
+    "Install with: pip install nemo_curator[cv2]"
+)
 
 
 def _qr_code_ratio(image: np.ndarray, row_index: Hashable | None = None) -> float:
     """Return the ratio of image area covered by all detected QR code(s), in [0, 1]."""
+    if cv2 is None:
+        raise ImportError(_CV2_INSTALL_HINT)
     img_shape = image.shape
     height, width = img_shape[:2]
     img_area = float(height * width)

nemo_curator/stages/interleaved/pdf/nemotron_parse/utils.py

@@ -32,6 +32,10 @@
 
 DEFAULT_MIN_CROP_PX = 10
 DEFAULT_MAX_PAGES = 50
+_CV2_INSTALL_HINT = (
+    "opencv-python-headless is required for Nemotron-Parse PDF processing. "
+    "Install with: pip install nemo_curator[cv2]"
+)
 
 
 def _render_scale_to_fit(page: Any, base_scale: float, max_wh: tuple[int, int] | None) -> float:  # noqa: ANN401
@@ -56,7 +60,10 @@ def _render_scale_to_fit(page: Any, base_scale: float, max_wh: tuple[int, int] |
 
 def _bitmap_to_rgb(bitmap: Any) -> Image.Image:  # noqa: ANN401
     """Convert a pypdfium2 bitmap to an RGB PIL image using OpenCV."""
-    import cv2
+    try:
+        import cv2
+    except ImportError as e:
+        raise ImportError(_CV2_INSTALL_HINT) from e
 
     arr = bitmap.to_numpy().copy()
     mode = bitmap.mode
@@ -173,7 +180,10 @@ def build_canvas(page_img: Image.Image, proc_size: tuple[int, int]) -> Image.Ima
 
     This lets us crop bboxes directly in the model's coordinate space.
     """
-    import cv2
+    try:
+        import cv2
+    except ImportError as e:
+        raise ImportError(_CV2_INSTALL_HINT) from e
     import numpy as np
 
     proc_h, proc_w = proc_size

nemo_curator/stages/interleaved/utils/image_utils.py

@@ -16,16 +16,27 @@
 
 from typing import TYPE_CHECKING
 
-import cv2
 import numpy as np
 from loguru import logger
 
+try:
+    import cv2
+except ImportError:
+    cv2 = None  # type: ignore[assignment]
+
 if TYPE_CHECKING:
     from collections.abc import Hashable
 
+_CV2_INSTALL_HINT = (
+    "opencv-python-headless is required for cv2-based image decoding. "
+    "Install with: pip install nemo_curator[cv2]"
+)
+
 
 def image_bytes_to_array(image_bytes: bytes, *, row_index: Hashable | None = None) -> np.ndarray | None:
     """Decode image bytes to RGB numpy array for OpenCV."""
+    if cv2 is None:
+        raise ImportError(_CV2_INSTALL_HINT)
     try:
         arr = np.frombuffer(image_bytes, dtype=np.uint8)
         image = cv2.imdecode(arr, cv2.IMREAD_COLOR)

nemo_curator/stages/text/embedders/vllm.py

@@ -18,7 +18,17 @@
 
 import torch
 from huggingface_hub import snapshot_download
-from vllm import LLM
+
+try:
+    from vllm import LLM
+
+    VLLM_AVAILABLE = True
+except ImportError:
+    VLLM_AVAILABLE = False
+
+    class LLM:  # dummy for type hints
+        pass
+
 
 from nemo_curator.backends.base import NodeInfo, WorkerMetadata
 from nemo_curator.stages.base import ProcessingStage
@@ -29,6 +39,11 @@
 if TYPE_CHECKING:
     from transformers import AutoTokenizer
 
+_VLLM_INSTALL_HINT = (
+    "vLLM is required for VLLMEmbeddingModelStage. "
+    "Install with: pip install nemo_curator[vllm]"
+)
+
 
 class VLLMEmbeddingModelStage(ProcessingStage[DocumentBatch, DocumentBatch]):
     def __init__(  # noqa: PLR0913
@@ -79,6 +94,8 @@ def _initialize_vllm(self, local_files_only: bool) -> None:
         to its config resolution code — passing a repo ID with a custom cache dir
         fails offline.
         """
+        if not VLLM_AVAILABLE:
+            raise ImportError(_VLLM_INSTALL_HINT)
         model_path = snapshot_download(
             self.model_identifier,
             cache_dir=self.cache_dir,

nemo_curator/stages/video/filtering/motion_vector_backend.py

@@ -17,15 +17,23 @@
 from typing import cast
 
 import av
-import cv2
 import numpy.typing as npt
 import torch
 from numpy.lib.recfunctions import structured_to_unstructured
 from torch import Tensor
 
+try:
+    import cv2
+except ImportError:
+    cv2 = None  # type: ignore[assignment]
+
 # We error on any video with a width or height less than this.
 # The motion detection algorithm can't handle any resolutions less than this.
 _MIN_SIDE_RESOLUTION = 256
+_CV2_INSTALL_HINT = (
+    "opencv-python-headless is required for the motion vector backend. "
+    "Install with: pip install nemo_curator[cv2]"
+)
 
 
 class VideoResolutionTooSmallError(Exception):
@@ -270,6 +278,8 @@ def check_if_small_motion(  # noqa: PLR0913
         MotionInfo object containing the results of the motion detection.
 
     """
+    if cv2 is None:
+        raise ImportError(_CV2_INSTALL_HINT)
     device = torch.device("cuda" if use_gpu else "cpu")
 
     global_sum_tensor = torch.tensor(0.0, device=device)

nemo_curator/utils/decoder_utils.py

@@ -28,15 +28,24 @@
 )
 
 import av
-import cv2
 import numpy as np
 import numpy.typing as npt
 
+try:
+    import cv2
+except ImportError:
+    cv2 = None  # type: ignore[assignment]
+
 if TYPE_CHECKING:
     from av.container import InputContainer
 
 from nemo_curator.utils.operation_utils import make_pipeline_named_temporary_file
 
+_CV2_INSTALL_HINT = (
+    "opencv-python-headless is required for target-resolution resizing in extract_frames. "
+    "Install with: pip install nemo_curator[cv2]"
+)
+
 
 class Resolution(NamedTuple):
     """Container for video frame dimensions.
@@ -659,6 +668,8 @@ def extract_frames(  # noqa: PLR0913
     )
 
     if target_res[0] > 0 and target_res[1] > 0:
+        if cv2 is None:
+            raise ImportError(_CV2_INSTALL_HINT)
         interpolation = cv2.INTER_CUBIC
         frames = np.array(
             [cv2.resize(frame, (target_res[1], target_res[0]), interpolation=interpolation) for frame in frames]

pyproject.toml

@@ -78,6 +78,10 @@ cuda12 = [
     "gpustat",
     "nvidia-ml-py",
 ]
+# Opt-in cv2 features; kept off `[all]` — wheel vendors CVE-flagged ffmpeg.
+cv2 = [
+    "opencv-python-headless",
+]
 vllm = ["vllm>=0.14.1; (platform_machine == 'x86_64' and platform_system != 'Darwin')"]
 
 # Inference Server (Ray Serve + vLLM) - for serving LLMs alongside Curator pipelines
@@ -218,7 +222,6 @@ text_cuda12 = [
 # Video Curation Dependencies
 video_cpu = [
     "av==17.1.0",  # ffmpeg 8.1.1 (CVE: was 7.0.2)
-    "opencv-python-headless",  # dedupe with vllm's headless
     "torchvision",
     "einops",
     "easydict",
@@ -257,7 +260,6 @@ math_cuda12 = [
 interleaved_cpu = [
     "matplotlib",
     "open_clip_torch",
-    "opencv-python-headless",  # dedupe with vllm's headless
     "Pillow",
     "pypdfium2",
     "s3fs>=2024.12.0",