Add cupy check to Load nodes with install instructions

BIM-VFI, SGM-VFI, and GIMM-VFI Load nodes now check for cupy at
load time and raise a clear error with the user's CUDA version and
the exact pip install command. Updated README with step-by-step
cupy install instructions.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

README.md

@@ -157,24 +157,29 @@ git clone https://github.com/Ethanfel/ComfyUI-Tween.git
 pip install -r requirements.txt
 ```
 
-### cupy
+### cupy (required for BIM-VFI, SGM-VFI, GIMM-VFI)
 
-`cupy` is required for BIM-VFI, SGM-VFI, and GIMM-VFI (optical flow warping). It will be auto-installed on first load based on your PyTorch CUDA version. If auto-install fails, install manually:
+`cupy` is needed for optical flow warping in BIM-VFI, SGM-VFI, and GIMM-VFI. EMA-VFI does **not** need cupy.
 
+The node will attempt to auto-install the correct cupy package on first load. If that fails, you'll see a clear error message in ComfyUI with install instructions. To install manually:
+
+1. Find your CUDA version:
    ```bash
-pip install cupy-cuda12x  # replace 12 with your CUDA major version (11 or 12)
+   python -c "import torch; print(torch.version.cuda)"
    ```
 
-### Requirements
+2. Install the matching cupy package:
+   ```bash
+   # CUDA 12.x
+   pip install cupy-cuda12x
 
-- PyTorch with CUDA
+   # CUDA 11.x
-- `cupy` (matching your CUDA version — for BIM-VFI, SGM-VFI, and GIMM-VFI)
+   pip install cupy-cuda11x
-- `timm` (for EMA-VFI and SGM-VFI)
+   ```
-- `gdown` (for BIM-VFI/EMA-VFI/SGM-VFI model auto-download)
-- `omegaconf`, `easydict`, `yacs`, `einops` (for GIMM-VFI)
-- `huggingface_hub` (for GIMM-VFI model auto-download)
 
-All dependencies except `cupy` are listed in `pyproject.toml` and installed automatically by ComfyUI Manager or pip.
+### Other dependencies
+
+All other dependencies (`gdown`, `timm`, `omegaconf`, `easydict`, `yacs`, `einops`, `huggingface_hub`) are listed in `pyproject.toml` and `requirements.txt`, and are installed automatically by ComfyUI Manager or pip.
 
 ## VRAM Guide
 

nodes.py

@@ -18,6 +18,28 @@ from .gimm_vfi_arch import clear_gimm_caches
 logger = logging.getLogger("Tween")
 
 
+def _check_cupy(model_name):
+    """Raise a clear error if cupy is not installed."""
+    try:
+        import cupy  # noqa: F401
+    except ImportError:
+        try:
+            cuda_ver = torch.version.cuda or "unknown"
+            major = int(cuda_ver.split(".")[0])
+            cupy_pkg = f"cupy-cuda{major}x"
+        except Exception:
+            cuda_ver = "unknown"
+            cupy_pkg = "cupy-cuda12x  # adjust to your CUDA version"
+        raise RuntimeError(
+            f"{model_name} requires cupy but it is not installed.\n\n"
+            f"Your PyTorch CUDA version: {cuda_ver}\n\n"
+            f"Install it with:\n"
+            f"  pip install {cupy_pkg}\n\n"
+            f"If you are unsure of your CUDA version, run:\n"
+            f"  python -c \"import torch; print(torch.version.cuda)\""
+        )
+
+
 def _compute_target_fps_params(source_fps, target_fps):
     """Compute oversampling parameters for target FPS mode.
 
@@ -138,6 +160,7 @@ class LoadBIMVFIModel:
     CATEGORY = "video/BIM-VFI"
 
     def load_model(self, model_path, auto_pyr_level, pyr_level):
+        _check_cupy("BIM-VFI")
         full_path = os.path.join(MODEL_DIR, model_path)
 
         if not os.path.exists(full_path):
@@ -1110,6 +1133,7 @@ class LoadSGMVFIModel:
     CATEGORY = "video/SGM-VFI"
 
     def load_model(self, model_path, tta, num_key_points):
+        _check_cupy("SGM-VFI")
         full_path = os.path.join(SGM_MODEL_DIR, model_path)
 
         if not os.path.exists(full_path):
@@ -1522,6 +1546,7 @@ class LoadGIMMVFIModel:
     CATEGORY = "video/GIMM-VFI"
 
     def load_model(self, model_path, ds_factor):
+        _check_cupy("GIMM-VFI")
         full_path = os.path.join(GIMM_MODEL_DIR, model_path)
 
         # Auto-download main model if missing