deepinsight/insightface · error · ImportError

ModelScope is not available. You have two options: 1. Instal

Error message

ModelScope is not available. You have two options:
1. Install ModelScope: pip install modelscope
2. Switch to OSS download mode by calling: inspireface.use_oss_download(True) before using InspireFace

What it means

The resource manager's constructor raises ImportError when ModelScope download mode is selected (use_modelscope) but the modelscope package is not importable in the environment. InspireFace offers two model download backends and this guard fails fast instead of erroring mid-download.

Source

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

        """
        self.user_home = Path.home()
        self.base_dir = self.user_home / '.inspireface'
        self.models_dir = self.base_dir / 'models'
        
        # ModelScope configuration
        self.use_modelscope = use_modelscope
        self.modelscope_model_id = modelscope_model_id
        self.modelscope_cache_dir = self.base_dir / 'ms'
        
        # Create directories
        self.base_dir.mkdir(exist_ok=True)
        self.models_dir.mkdir(exist_ok=True)
        if self.use_modelscope:
            self.modelscope_cache_dir.mkdir(exist_ok=True)
            
        # Check ModelScope availability
        if self.use_modelscope and not MODELSCOPE_AVAILABLE:
            raise ImportError(
                "ModelScope is not available. You have two options:\n"
                "1. Install ModelScope: pip install modelscope\n" 
                "2. Switch to OSS download mode by calling: inspireface.use_oss_download(True) before using InspireFace"
            )
        
        # Model URLs
        self._MODEL_LIST = {
            "Pikachu": {
                "url": "https://inspireface-1259028827.cos.ap-singapore.myqcloud.com/inspireface_modelzoo/t4/Pikachu",
                "filename": "Pikachu",
                "md5": "5037ba1f49905b783a1c973d5d58b834a645922cc2814c8e3ca630a38dc24431"
            },
            "Megatron": {
                "url": "https://inspireface-1259028827.cos.ap-singapore.myqcloud.com/inspireface_modelzoo/t4/Megatron",
                "filename": "Megatron",
                "md5": "709fddf024d9f34ec034d8ef79a4779e1543b867b05e428c1d4b766f69287050"
            },
            "Megatron_TRT": {

View on GitHub (pinned to 7fadd420c2)

Solutions

1. pip install modelscope
2. Or switch backend: call inspireface.use_oss_download(True) before any InspireFace usage to use the OSS downloader
3. Pin a working modelscope version if a dependency conflict broke the import (pip install 'modelscope>=1.9')

Example fix

# before
inspireface.use_oss_download(False)  # ModelScope mode
r = inspireface.Resource()  # ImportError
# after (option 1)
# pip install modelscope
# after (option 2)
inspireface.use_oss_download(True)
r = inspireface.Resource()

try:
    import modelscope  # noqa
except ImportError:
    import inspireface
    inspireface.use_oss_download(True)

try:
    resource = Resource()
except ImportError:
    inspireface.use_oss_download(True)
    resource = Resource()

When it happens

Trigger: Constructing the resource manager / triggering first model access after opting into ModelScope mode without having installed the modelscope package (or in an env where its import failed).

Common situations: Following docs that recommend ModelScope for users near China; creating a fresh venv/conda env and copying code but not deps; modelscope installed but broken by a dependency conflict so the import fails.

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

• ModelScope is not available. Please install it with: pip ins
• Model file '{model_name}' not found in downloaded repository
• Failed to download model from ModelScope: {e}
• Failed to download model: {e}
• Unable to import dependency onnxruntime.

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