deepinsight/insightface · error · ImportError

ModelScope is not available. Please install it with: pip ins

Error message

ModelScope is not available. Please install it with: pip install modelscope

What it means

_download_from_modelscope re-checks MODELSCOPE_AVAILABLE before calling snapshot_download and raises ImportError with the install hint if the package is missing. Unlike the constructor check, this fires at download time, typically because ModelScope became unavailable after object creation (or the object was constructed in OSS mode and switched).

Source

Thrown at cpp-package/inspireface/python/inspireface/modules/utils/resource.py:118

            },
            "Gundam_RK3588": {
                "url": "https://inspireface-1259028827.cos.ap-singapore.myqcloud.com/inspireface_modelzoo/t4/Gundam_RK3588",
                "filename": "Gundam_RK3588",
                "md5": "66070e8d654408b666a2210bd498a976bbad8b33aef138c623e652f8d956641e"
            }
        }

    def _download_from_modelscope(self, model_name: str) -> str:
        """Download model from ModelScope platform
        
        Args:
            model_name: Name of the model to download
            
        Returns:
            str: Path to the downloaded model file
        """
        if not MODELSCOPE_AVAILABLE:
            raise ImportError("ModelScope is not available. Please install it with: pip install modelscope")
            
        print(f"Downloading model '{model_name}' from ModelScope...")
        
        try:
            # Download specific model file from ModelScope
            cache_dir = snapshot_download(
                model_id=self.modelscope_model_id,
                cache_dir=str(self.modelscope_cache_dir),
                allow_file_pattern=[model_name]  # Only download the specific model file
            )
            
            model_file_path = Path(cache_dir) / model_name
            
            if not model_file_path.exists():
                raise FileNotFoundError(f"Model file '{model_name}' not found in downloaded repository")
                
            print(f"ModelScope download completed: {model_file_path}")
            return str(model_file_path)

View on GitHub (pinned to 7fadd420c2)

Solutions

pip install modelscope and retry the download
If you can't install it, enable OSS mode first: inspireface.use_oss_download(True)
Verify with python -c 'import modelscope' that the import truly succeeds (watch for conflicting deps)

Example fix

# before
path = resource.get_model('pikachu')  # ImportError: ModelScope is not available
# after
# pip install modelscope
path = resource.get_model('pikachu')

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
if importlib.util.find_spec('modelscope') is None:
    raise SystemExit('pip install modelscope or call inspireface.use_oss_download(True)')

Try / catch

try:
    path = resource.get_model(name)
except ImportError:
    inspireface.use_oss_download(True)
    path = resource.get_model(name)

Prevention

Verify importability of modelscope in the deploy env, not just pip list
Smoke-test get_model during container build

When it happens

Trigger: Calling get_model()/resource download paths that route to _download_from_modelscope_with_cache in an environment where import modelscope fails or wasn't installed.

Common situations: Deploying to a container built without modelscope; uninstalling modelscope between process setup and download; a crash of a lazily-imported modelscope submodule setting the availability flag false.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

AI-assisted analysis of deepinsight/insightface@7fadd420c2 (2026-08-28). Data as JSON: /api/errors/0ef5b891f983aaaf. Report an issue: GitHub.